Skip to content

System Overview¶

Service map¶

┌─────────────────────────────────────────────────────────────────┐
│  Warehouse (on-prem)                                            │
│                                                                 │
│   Barcode Scanners ──TCP/MQTT──▶ ┌──────────────────────────┐  │
│   ESP32 Devices ────────────────▶ │  ASP.NET Core DMS        │  │
│                                   │  .NET 6  :5269           │  │
│                                   │  /health  /swagger       │  │
│                                   └─────────┬────────────────┘  │
│                                             │                   │
│                            ┌────────────────┴──────────────┐   │
│                            │  PostgreSQL 16                │   │
│                            │  dms-layered                  │   │
│                            │  ├── msort schema  (Core)     │   │
│                            │  └── meesho schema (Meesho)   │   │
│                            └───────────────────────────────┘   │
│                                                                 │
└─────────────────────────┬───────────────────────────────────────┘
                          │ HTTPS (outbound only)
                          ▼
               ┌──────────────────────┐
               │  Partner API         │
               │  (Meesho / Myntra)   │
               │  AWB routing data    │
               │  InScan + manifest   │
               └──────────────────────┘

Local dev only: The Partner API is replaced by the Mock Partner API running at :5000.

Two-layer design¶

Core Layer — `msort` schema¶

Tenant-agnostic. Every client uses this code unchanged.

Component	Purpose
`ScannerService`	TCP listener for barcode scanner events; hot path
`IClientService`	Interface seam — swapping clients here, not in code
`BinService`	Sort bin state machine
`BotService`	Robot assignment and drop commands
`InfeedService`	Conveyor infeed management
`SessionService`	Single active session enforcement
`RuntimeConfigStore`	In-memory KV cache of sorter profile config
`ScannerLifecycleHostedService`	Background service: scanner heartbeat + recovery

Meesho Layer — `meesho` schema¶

Meesho-specific integration. Isolated from Core via IClientService.

Component	Purpose
`MeeshoHttpClient`	Typed HTTP client with token refresh
`DataSyncWorker`	Polls Meesho AWB API → writes `data_sync` table
`OutboxWorker`	Drains `inscan_sync` + `motherbag_sync` → pushes to Meesho API
`TokenRefreshWorker`	Proactively refreshes bearer token before expiry
`ManifestService`	Seals a bag: computes AWB list → calls `/hub/manifest/close`

Request flow — parcel scan¶

sequenceDiagram
    participant S as Scanner (TCP)
    participant SS as ScannerService
    participant CS as IClientService (Meesho)
    participant DS as data_sync table
    participant BS as BinService
    participant PE as parcel_events

    S->>SS: AWB scan event
    SS->>CS: GetRoutingDecision(awb)
    CS->>DS: SELECT next_node FROM data_sync WHERE awb=?
    DS-->>CS: BLR_HUB
    CS-->>SS: RoutingDecision{binId=42, destination="BLR_HUB"}
    SS->>BS: AssignParcelToBin(binId=42)
    BS-->>SS: ok
    SS->>PE: INSERT parcel_events (Scanned, awb, binId)
    SS-->>S: ACK

Middleware pipeline¶

Request
  │
  ├── ExceptionHandlerMiddleware    (global error → JSON response)
  ├── SessionGateMiddleware         (blocks scan API if no active session)
  ├── RateLimitMiddleware           (per-IP rate limiting)
  ├── IdempotencyFilter             (deduplicates POST requests by key)
  └── Controller

Multi-tenant design (RFC FLX-ENG-RFC-001)¶

The platform is evolving from single-tenant (Meesho only) to multi-tenant. The IClientService seam is already in place. Client variation is expressed through:

Tenant configuration — values that differ per client (endpoints, SLAs, limits) → carried in signed manifest
Feature flags — same capability, on/off per client → feature registry in manifest
Strategy/plugin interfaces — business logic that genuinely differs → IClientService implementation selected by manifest key
Deployment topology — isolation requirements → IaC module variant, same artifact

See RFC FLX-ENG-RFC-001 for the full proposal.