Vytra Engineering Hub
Release Monitor & Technical Documentation
f0ed698f0ed698
- Switch production API base URL to custom domain api.vytra.co.in
f43ca03
- Set Vytra logo as notification largeIcon and vibrant brand color
e213c41
- Remove in-app dynamic island from mobile
dfe43b8
- Enable Dynamic Island widget across mobile and web with centered punch-hole alignment
d985887
- Fix missing Secrets import on CI, add HyperOS live updates permission
1ae3e4b
- Add POST_PROMOTED_NOTIFICATIONS permission and live updates attributes for Xiaomi HyperOS
51766a8
- Fix checkout stock validation, add bottom slide-up cart notification, add HyperOS live order tracking and in-app delivery card
a65939f
- Flipkart floating pill navbar, cart integration, progressive backdrop blur, profile picture 25mb persistence, and symmetrical 3px border spacing
a65939f
- Flipkart-style symmetrical floating pill navigation dock
- Integrated Cart as 5th tab with live item badge counter
- Progressive backdrop blur and background fade layer behind navbar
- Profile picture persistence in MongoDB Atlas and 25MB upload limit
- Mobile gallery path resolution and image downscaling
1. High-Level System Topology
End-to-end request lifecycle from customer and merchant devices to database and cloud delivery microservices.
2. Core Architectural Pillars
Atomic Inventory Mutex
Cart increments, order checkouts, and cancellations use atomic MongoDB $inc operations with strict inventory bounds checking, completely eliminating race conditions.
Dual-Layer Cache Resilience
Cloud Redis TLS with an automatic in-memory RAM fallback ensures that if cloud cache fails, the API serves recommendations and cached products without downtime.
Hybrid Recommendation Engine
A 3-tier pipeline combining historical order co-occurrence aggregation, category complement matrices, and store bestsellers with 600s cache TTL.
HyperOS Live Tracking
Real-time delivery progress updates integrated with Xiaomi HyperOS promoted notifications and an in-app dynamic island widget aligned with phone camera punch-holes.
3. Data Schema & Entity Relationships
MongoDB Collections Overview
| Collection | Primary Fields | Key Indexes | Purpose |
|---|---|---|---|
users |
name, email, password, role, addresses |
{ email: 1 } UNIQUE |
Multi-role authentication (Customer, Shopkeeper, Admin). |
shops |
name, owner, location, category, isVerified |
{ location: "2dsphere" } |
Local merchant registry with geospatial distance queries. |
products |
name, price, stockQuantity, shop, category, images |
{ shop: 1, isAvailable: 1 }, text index |
Catalog management with live inventory bounds and text search. |
carts |
userId, items: [{ productId, quantity }] |
{ userId: 1 } UNIQUE |
Persistent customer carts updated via atomic array operations. |
orders |
userId, items, totalAmount, status, deliveryAddress |
{ userId: 1, createdAt: -1 }, { 'items.productId': 1 } |
Order lifecycle tracking, cancellation locks & co-occurrence mining. |
4. Order Lifecycle & Inventory Integrity
State Machine & Cancellation Rules
$inc: { stockQuantity: +quantity }
Once an order transitions to Dispatched, Shipped, or Delivered, cancellation is strictly locked on both frontend and backend to protect merchant economics and live driver dispatch.
Problem: Customers adding items to cart had no cross-sell discovery, resulting in lower basket sizes and missing grocery pairings.
Architecture Solution: Built a 3-tier hybrid recommendation pipeline on NestJS with Redis caching (600s TTL). Tier 1 performs MongoDB order co-occurrence aggregation on past carts. Tier 2 uses a complementary category affinity matrix (e.g. Milk ➔ Bread, Eggs, Tea). Tier 3 falls back to same-shop in-stock bestsellers. On frontend, added an interactive horizontal carousel with instant 1-tap [+ ADD], steppers, and left/right arrow buttons.
Impact: Sub-10ms response time for repeat carts; zero-latency addition to cart without screen reloads.
Problem: The floating pill nav bar container had transparent margins and SafeArea insets, causing taps around and underneath the bar to click buttons (e.g. Log Out) and links scrolled behind it.
Architecture Solution: Wrapped the bottom nav bar in customer_home.dart with an opaque GestureDetector(behavior: HitTestBehavior.opaque, onTap: () {}, onVerticalDragStart: (_) {}) to intercept and absorb all touch events. Increased bottom scroll clearance from 90px to 120px across Account, Cart, Orders, and Wishlist pages.
Problem: The Account screen had a hardcoded stale string Vytra v1.0.3 (Build 3), and daily builds on GitHub Actions were firing multiple times per day on every tag.
Architecture Solution: Integrated package_info_plus to dynamically query the running build at runtime. In GitHub Actions, scheduled APK compilation once daily after 4:00 AM IST (45 22 * * *) and computed incremental versionCode (13 + run_number) passed directly to flutter build apk, ensuring Android permits in-place upgrades.
Problem: Transactional emails used generic purple gradients and emojis that didn't align with Vytra's earthy chocolate and gold identity.
Architecture Solution: Redesigned Password Reset OTP, Order Confirmation, Order Status Update, and Welcome templates with clean table-based layouts, dark chocolate gradients (#1E1B18 to #38240D), warm gold accents (#D4A373), and crisp serif-free typography without emojis.
Problem: Rapidly tapping the "Add to Cart" button created duplicate array entries in MongoDB carts and produced race conditions on quantity updates.
Architecture Solution: Upgraded cart.service.ts to atomic MongoDB $inc and conditional $push with automatic deduplication. Added an in-flight locking set (_pendingProductIds) and quick-commerce stepper on the Flutter frontend.
Problem: Cloud Redis connections on free-tier providers could drop or timeout, risking application errors.
Architecture Solution: Enhanced cache.service.ts with rediss:// TLS support, lazy connection, and an autonomous in-memory Map fallback with automatic TTL expiration.
Problem: Customers needed a self-serve way to cancel mistakenly placed orders, but without cancelling dispatched deliveries.
Architecture Solution: Implemented PUT /orders/:id/cancel with strict state machine validation (blocked if Dispatched, Delivered, or Cancelled) and automatic stock restoration ($inc: { stockQuantity: quantity }).
Architecture Solution: Integrated Xiaomi HyperOS promoted notification attributes and engineered a Flutter dynamic island pill widget that auto-detects and centers itself directly under modern phone camera punch-holes.
Architecture Solution: Designed unified schema models supporting Customer B2C shopping, Shopkeeper B2B wholesale sourcing, and Distributor product fulfillment.
https://api.vytra.co.in/api/v1
Registers a new customer, shopkeeper, or delivery agent. Returns JWT auth credentials upon creation.
{
"name": "Sayan Pandit",
"email": "sayan@example.com",
"password": "StrongPassword123!",
"role": "customer" // "customer" | "shopkeeper" | "delivery"
}
{
"statusCode": 201,
"accessToken": "eyJhbGciOiJIUzI1NiIsIn...",
"user": {
"id": "674128f...",
"name": "Sayan Pandit",
"email": "sayan@example.com",
"role": "customer"
}
}
Authenticates email and password. Generates Bearer JWT with 30-day session lifetime.
{
"email": "sayan@example.com",
"password": "StrongPassword123!"
}
{
"statusCode": 200,
"accessToken": "eyJhbGciOiJIUzI1NiIsIn...",
"user": {
"id": "674128f...",
"name": "Sayan Pandit",
"email": "sayan@example.com",
"role": "customer"
}
}
Generates a cryptographically secure 6-digit numeric OTP with 10-minute expiry and sends via Titan/Resend luxury HTML email template.
{
"email": "customer@vytra.co.in"
}
{
"success": true,
"message": "Reset verification code sent to your email"
}
Validates OTP code and updates user bcrypt hash. Invalidates previous tokens.
{
"email": "customer@vytra.co.in",
"otp": "481920",
"newPassword": "NewSecurePassword2026!"
}
{
"success": true,
"message": "Password updated successfully. Please log in with your new password."
}
Retrieves the active cart for the authenticated user, populated with product stock, pricing, and live total calculations.
{
"_id": "674128f...",
"user": "674128f...",
"items": [
{
"product": {
"_id": "6741a2...",
"name": "Tata Tea Gold 500g",
"price": 280,
"stock": 45,
"category": "Groceries",
"images": ["https://..."]
},
"quantity": 2,
"price": 280
}
],
"totalAmount": 560
}
Safely adds an item to cart or increments quantity using atomic MongoDB $inc mutex, preventing race condition over-ordering.
{
"productId": "6741a2e4...",
"quantity": 1
}
{
"success": true,
"cart": {
"totalItems": 3,
"totalAmount": 840
}
}
Updates item quantity directly. If quantity is 0, item is automatically pruned from the cart.
| Parameter | Type | Description |
|---|---|---|
productId * | ObjectId | Target product ID |
{
"quantity": 3
}
Sub-10ms intelligent cross-sell recommendation engine. Reads cart items, queries Upstash Redis TLS cache, and generates complementary items within the same shop ordered by price tier and category affinity.
| Parameter | Type | Description |
|---|---|---|
shopId | String | Restricts suggestions to products stocked in this shop |
productIds | Comma-separated Strings | List of product IDs currently in cart to exclude |
limit | Number | Default 6 (max 12) |
{
"success": true,
"source": "redis_cache", // "redis_cache" | "mongo_pipeline"
"recommendations": [
{
"_id": "6741b8...",
"name": "Britannia Marie Gold 300g",
"price": 40,
"category": "Snacks",
"stock": 80,
"images": ["https://..."],
"relevanceScore": 0.94
},
{
"_id": "6741c1...",
"name": "Sugar 1kg",
"price": 48,
"category": "Groceries",
"stock": 120,
"images": ["https://..."],
"relevanceScore": 0.89
}
]
}
Validates stock with atomic decrement, empties cart, and spawns new order in pending status. Triggers HyperOS live notification pipeline.
{
"shopId": "67419a...",
"items": [
{ "productId": "6741a2...", "quantity": 2 }
],
"deliveryAddress": {
"street": "12/A College Road",
"city": "Kolkata",
"postalCode": "700001",
"coordinates": [88.3639, 22.5726]
},
"paymentMethod": "cod" // "cod" | "upi" | "card"
}
Cancels an order if it is in pending or confirmed state. Once an order is packed or out_for_delivery, cancellation is strictly rejected with 409 Conflict. Restores product inventory via $inc.
{
"success": true,
"message": "Order #VY-8921 cancelled successfully. Stock has been restored.",
"order": {
"_id": "6741d4...",
"status": "cancelled",
"cancellationTimestamp": "2026-10-02T01:30:00.000Z"
}
}
Paginated product catalog query supporting fuzzy regex search, category filtering, and shop filtering.
| Parameter | Type | Description |
|---|---|---|
search | String | Fuzzy title match |
category | String | Category filter (Groceries, Dairy, Snacks) |
shopId | ObjectId | Limit to specific shop vendor |
page | Number | Page number (default 1) |
limit | Number | Items per page (default 20) |
Finds verified open shops within a specified radius using MongoDB 2dsphere indexing and calculates straight-line distance in kilometers.
| Parameter | Type | Description |
|---|---|---|
lat * | Float | Customer GPS latitude |
lng * | Float | Customer GPS longitude |
radius | Float | Radius in km (default 5.0) |
[
{
"_id": "67419a...",
"name": "Green Supermarket",
"address": "45 Park St, Kolkata",
"isOpen": true,
"distanceKm": 1.2,
"rating": 4.8
}
]
master appears here instantly.No commits match your search.