doormilxpress_astryx/DOORMILE_LOGISTICS_ARCHITECTURE.md

Doormile Logistics & Commercial CRM Platform — Architecture & Operational Manual

---

1. Executive Summary & Ecosystem Overview

Doormile is a production-grade commercial parcel logistics, hyper-local courier, and field CRM platform engineered for the Indian market (with active hub operations in Coimbatore, Hyderabad, Bengaluru, and Chennai).

The platform connects direct B2C shippers, enterprise commercial clients (tenants), logistics partner fleets, field sales and survey teams, hub sorting operations, and delivery milers (riders) into an AI-orchestrated logistics pipeline.

┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                       DOORMILE UNIFIED ECOSYSTEM                                       │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

 ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────────┐ ┌─────────────────────────┐
 │  Customer App (B2C)  │ │   Miler Rider App    │ │ Doormile Express Console │ │      Doormile CRM       │
 │    (Flutter App)     │ │    (Flutter App)     │ │   (krow_talent_app)      │ │   (Field Ops / Sales)   │
 └──────────┬───────────┘ └──────────┬───────────┘ └────────────┬─────────────┘ └────────────┬────────────┘
            │                        │                          │                            │
            │ Firebase OTP           │ Phone + PIN Auth         │ JWT / Tenant-Scoped        │ JWT / Admin & Field
            ▼                        ▼                          ▼                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                             DOORMILE GO + FIBER BACKEND (api.doormile.com)                             │
│                         200 REST Endpoints + WebSocket Live Telemetry Gateway                          │
├────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ • Multi-Tenancy Isolation Layer (Doormile Ops vs Partner Tenants)                                      │
│ • Field Sales & Client CRM Registration Engine (/crm/clients)                                          │
│ • Market Survey & Competitor Intelligence Engine (/admin/competitor-branches, /carrier-pricing)        │
│ • AI Autonomous Dispatch & Miler Assignment Orchestrator (Claude Sonnet + JARVIS / routemate)          │
│ • Line-haul Hub-to-Hub Tripsheet & Transit Tracker                                                     │
│ • Proof-of-Delivery (POD), Receiver OTP Verification & Idempotent Payments                             │
└──────────────────────────┬─────────────────────────────┬───────────────────────────┬───────────────────┘
                           │                             │                           │
                           ▼                             ▼                           ▼
            ┌─────────────────────────────┐ ┌─────────────────────────┐ ┌────────────────────────────┐
            │   PostgreSQL + pgvector     │ │     Redis 7 Cluster     │ │       NATS JetStream       │
            │   (37 Relational Tables)    │ │  (GEO / Spatial / TTL)  │ │   (Asynchronous Events)    │
            └─────────────────────────────┘ └─────────────────────────┘ └────────────────────────────┘
                           ▲                             ▲                           ▲
                           │                             │                           │
                           └─────────────────────────────┼───────────────────────────┘
                                                         │
                                                         ▼
                                          ┌─────────────────────────────┐
                                          │      AI DISPATCH LAYER      │
                                          │  (Claude Sonnet + pgvector  │
                                          │   routemate.workolik.com)   │
                                          └─────────────────────────────┘

---

2. System Architecture & Component Responsibilities

Application / Layer	Technology Stack	Primary Purpose & Key Features
Go Backend Core (doormile_backend)	Go 1.22+, Fiber v2, GORM, PostgreSQL 16 (pgvector), Redis 7, NATS JetStream	200 REST routes, transactional integrity, rate-limiting, geo-spatial miler indexing (GEOSEARCH), line-haul tripsheets, idempotent state conversions.
Express Dispatch Console (krow_talent_app)	React 19, Vite 6, Tailwind CSS, shadcn/ui, Leaflet Maps, React Query 5	Real-time operations board, live rider breadcrumbs & telemetry, multi-order Excel upload, wave economics (Morning/Afternoon/Evening), in-console deterministic Doormile AI Copilot.
Commercial CRM & Field Sales (doormile_crm)	React 18, Vite, Material-UI v5 (MUI) / Tailwind, Brand Red Theme (#C01227)	Field client onboarding, GPS survey verification, competitor branch tracking, benchmark carrier rate cards, lead management, sales executive dashboard.
Miler Rider App	Flutter (Dart), Local SQLite, REST API, Background GPS	Shift & break logging, turn-by-turn assignments, doorstep customer reached marker, parcel collection, receiver OTP proof of delivery, photo/signature upload, daily earnings.
Customer App (B2C)	Flutter (Dart), Firebase OTP Auth	On-demand courier booking, dynamic pricing estimates, live WebSocket parcel tracking, saved address book.
AI Dispatch & Reasoning	Python Swarm (JARVIS), Claude Sonnet (routemate.workolik.com)	Contextual candidate scoring (distance, load, rating, 30-day on-time performance), vector similarity RAG memory, 5-second automatic fallback.

---

3. The Front Doors: Client & Console Applications

3.1. Doormile Express Console (krow_talent_app)

The primary real-time operational cockpit for dispatchers and hub managers:

• Dispatch Board (/doormile/dispatch): Monitors active riders, live GPS coordinates, breadcrumb trails, battery status, and wave economics.
• Orders & Deliveries (/doormile/orders, /doormile/deliveries): Manages pending bookings, reconciles optimizer previews, and tracks consignments across delivery tabs.
• Fleet & Linehaul (/doormile/hubs, /doormile/vehicles, /doormile/tripsheets): Hub manifests, barcode scanning, container transfers between sorting centers and delivery hubs.
• Doormile AI Assistant (lib/assistant/): In-console copilot executing deterministic queries over backend endpoints for live order stats, rider status, and conversational booking creation.

3.2. Doormile CRM & Field Operations (doormile_crm)

Dedicated commercial console for sales reps, field surveyors, and account managers:

• Field Client Onboarding (/clients \rightarrow doormile_clients):
  • Registers B2B clients directly from field visits.
  • Captures on-site GPS verification: surveylat, surveylong, survey_address, survey_zone, survey_pincode.
  • Captures commercial profiling: business_type, shipping_frequency, logistics_segment, parcel_volume, active_contracts, logistics_provider, provider_efficiency, and data_consent (basic vs full).
• Competitor Market Survey (/survey \rightarrow admin/competitor-branches):
  • Tracks physical branch presence of competing logistics providers (DTDC, Professional, ST Courier, Delhivery, etc.) across target zones.
  • Logs competitor contact numbers, addresses, pickup timings, and service strengths.
• Carrier Pricing Benchmark (/pricing \rightarrow admin/carrier-pricing):
  • Compares market courier rate cards against Doormile's pricing matrices for competitive bidding.
• Commercial Bookings (/bookings \rightarrow admin/bookings):
  • Enables sales managers to originate bookings on behalf of enterprise accounts and simulate immediate quotes (/admin/pricing/quote).
• Team & Rep Management (/team-users \rightarrow admin/users):
  • Manages field representatives, sales executives, and their assigned operational locations.

---

4. Comprehensive Data Models & Domain Architecture

                               ┌──────────────────────────────────────────────┐
                               │               DoormileClient                 │
                               │          (doormile_clients table)            │
                               │  - Field CRM Lead & GPS Survey               │
                               │  - Volume, Frequency, Competitor Intel       │
                               └──────────────────────┬───────────────────────┘
                                                      │ Converts to Active Account
                                                      ▼
                               ┌──────────────────────────────────────────────┐
                               │                    Tenant                    │
                               │         (Commercial Client Entity)           │
                               └──────────────────────┬───────────────────────┘
                                                      │
                       ┌──────────────────────────────┴──────────────────────────────┐
                       │                                                             │
                       ▼                                                             ▼
        ┌─────────────────────────────┐                               ┌─────────────────────────────┐
        │        TenantLocation       │                               │        TenantPricing        │
        │  (Kitchen/Depot/Branch Site)│                               │    (Custom Rate Card Matrix)│
        └──────────────┬──────────────┘                               └──────────────┬──────────────┘
                       │                                                             │
                       │ Originated Order                                            │ Pricing Rules
                       ▼                                                             ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                             PickupBooking                                              │
│                                       (pickupbookings table)                                           │
│  - Booking Source: "Customer_App" | "CRM_Console"                                                      │
│  - Addresses, Geo-coords, Dimensions, Service Option (Normal/Fast/Superfast)                           │
│  - Lifecycle: Created -> Miler_Assigned -> Pickup_Scheduled (Accepted) -> Arrived                     │
└───────────────────────────────────────────────────┬────────────────────────────────────────────────────┘
                                                    │
                               Miler Doorstep Pickup Complete
                                                    ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              Consignment                                               │
│                                         (consignments table)                                           │
│  - Tracking Number, Origin Hub, Current Hub, Destination Hub                                           │
│  - Secret Receiver Delivery OTP (6 digits)                                                             │
│  - Lifecycle: Collected_By_Miler -> Inwarded_at_Hub -> Tripsheet_Loaded -> Out_for_Delivery -> Delivered│
└───────────────────┬───────────────────────────────────────────────────────────────┬────────────────────┘
                    │                                                               │
     Line-haul Transfer Between Hubs                                  Last-Mile Customer Handover
                    ▼                                                               ▼
┌──────────────────────────────────────┐                         ┌──────────────────────────────────────┐
│        Tripsheet & TripsheetItem     │                         │            DeliveryProof             │
│  - Source Hub to Destination Hub     │                         │  - Verified Receiver OTP             │
│  - Scanned Vehicle Manifest          │                         │  - Signature / Photo URL / Geolocation│
└──────────────────────────────────────┘                         └──────────────────────────────────────┘

---

5. End-to-End Operational Lifecycle Workflows

sequenceDiagram
    autonumber
    actor Rep as Field Sales Rep (CRM)
    actor Client as B2B Client / Shipper
    participant CRM as Doormile CRM Console
    participant Backend as Go Backend (api.doormile.com)
    participant Redis as Redis 7 (Spatial GEO)
    participant AI as AI Dispatcher (Claude Sonnet)
    actor Miler as Miler (Rider App)
    participant Hub as Doormile Hub / Sorting Center
    actor Receiver as Consignee (Receiver)

    Note over Rep,CRM: 1. Commercial Acquisition & Survey
    Rep->>CRM: Conduct On-site Field Survey & Register Client
    CRM->>Backend: POST /crm/clients (GPS coords, business profile, volume)
    Backend->>Backend: Persist DoormileClient record & Map to Tenant

    Note over Client,Backend: 2. Booking Origination
    Client->>Backend: Create Shipment Order (POST /admin/expressbooking)
    Backend->>Backend: Validate Rate Card, Calculate Price & Create PickupBooking (Pending_Pickup)

    Note over Backend,Miler: 3. AI Dispatch & First-Mile Pickup
    Backend->>Redis: GEOSEARCH milers:locations (10 km radius)
    Redis-->>Backend: Return Active Miler Candidates
    Backend->>AI: Send Candidates & Booking Parameters
    AI-->>Backend: Selected Miler with Reasoning (AgentDecision logged)
    Backend->>Backend: Create BookingAssignment (Status: Miler_Assigned)
    Backend->>Miler: Push Notification: New Pickup Assigned
    Miler->>Backend: Accept Assignment (POST /miler/assignments/:id/accept)
    Miler->>Backend: Reached Doorstep (POST /miler/bookings/:id/reached)
    Miler->>Backend: Collect COD & Complete Pickup (POST /miler/bookings/:id/pickup-complete)
    
    Note over Backend: 4. Handoff & Consignment Conversion
    Backend->>Backend: Convert Booking -> Consignment (Status: Collected_By_Miler)
    Backend->>Backend: Issue Secure 6-digit Delivery OTP (SMS/Push to Receiver)

    alt Scenario A: Hyperlocal Route (Same Zone)
        Miler->>Backend: Start Delivery (POST /miler/consignments/:id/start-delivery)
        Note over Backend: Status -> Out_for_Delivery
        Miler->>Receiver: Reach Delivery Location & Request OTP
        Miler->>Backend: Deliver with Receiver OTP + Signature (POST /miler/consignments/:id/deliver)
        Backend->>Backend: Verify OTP, Store DeliveryProof -> Status: Delivered
    else Scenario B: Hub-and-Spoke Linehaul Route
        Miler->>Hub: Inward Parcel to Origin Hub (POST /hub/bookings/:id/inbound)
        Note over Hub: Inwarded_at_Hub (Assigned to Shelf)
        Hub->>Hub: Build Tripsheet & Load into Line-haul Vehicle (POST /admin/tripsheets)
        Note over Hub: Status -> In_Transit
        Hub->>Hub: Destination Hub Scan & Offload (PUT /tripsheets/:id/arrive)
        Hub->>Miler: Assign Last-Mile Delivery Rider (POST /hub/bookings/:id/assign-miler)
        Miler->>Receiver: Handover Parcel with Receiver OTP -> Status: Delivered
    end

---

6. Comprehensive API Surface Directory

6.1. CRM & Field Sales APIs (/crm, /admin)

• POST /crm/clients — Register on-site field leads and GPS surveyed clients.
• GET /crm/clients — List all registered CRM clients (open access for field reps).
• GET /crm/clients/:id | PUT /crm/clients/:id | DELETE /crm/clients/:id — Manage client details.
• GET /admin/competitor-branches | POST /admin/competitor-branches — Market intelligence branch registry.
• GET /admin/carrier-pricing | POST /admin/carrier-pricing — Market benchmark courier rate cards.
• POST /admin/pricing/quote — Simulate delivery quote for commercial clients.

6.2. Operations & Dispatch Console APIs (/admin)

• POST /admin/login — Staff & executive authentication.
• GET /admin/dashboard — Platform-wide KPI overview.
• GET /admin/bookings — Search and filter raw booking queue.
• POST /admin/expressbooking — Single express order creation.
• POST /admin/expressbooking/bulk — Excel/CSV multi-order bulk generation.
• POST /admin/expressbooking/dispatch — Batch dispatch trigger.
• POST /admin/bookings/:id/assign-miler — Manual rider assignment.
• POST /admin/bookings/bulk-cancel — Bulk cancel pending orders.
• GET /admin/consignments — List active consignments and tracking state.
• GET /admin/tripsheets | POST /admin/tripsheets — Create and track line-haul manifests.
• PUT /admin/tripsheets/:id/dispatch | PUT /admin/tripsheets/:id/arrive — Hub departures & arrivals.

6.3. Hub Console APIs (/hub)

• POST /hub/login — Hub staff login.
• GET /hub/dashboard — Station-level metrics.
• GET /hub/bookings/unassigned — Hub pickup queue (tenant-scoped).
• POST /hub/bookings/:id/inbound — Inward inbound barcode scan with shelf assignment.
• POST /hub/bookings/:id/auto-assign — Synchronous AI assignment.
• POST /hub/bookings/batch-assign — Greedy nearest-miler queue clearing.
• GET /hub/messages | POST /hub/messages/:id — Hub-to-miler direct chat channel.

6.4. Miler Mobile APIs (/miler)

• POST /miler/login | POST /miler/verify-pin — 4-digit PIN authentication.
• PUT /miler/location — Periodic GPS telemetry ping (written to Redis milers:locations).
• PUT /miler/availability — Toggle state (Available, Break, Offline).
• POST /miler/duty/start | PUT /miler/duty/end — Daily duty logs.
• GET /miler/assignments — Pending and active job queue.
• POST /miler/assignments/:id/accept | POST /miler/assignments/:id/reject — Assignment response.
• POST /miler/bookings/:id/reached — Record doorstep arrival timestamp & coordinates.
• POST /miler/bookings/:id/pickup-complete — Complete collection & convert to Consignment.
• POST /miler/consignments/:id/start-delivery — Move parcel to out-for-delivery.
• POST /miler/consignments/:id/deliver — Final delivery with receiver OTP & signature proof.
• POST /miler/consignments/:id/skip — Record failed delivery attempt / skip.

---

7. Multi-Tenancy, Security & Integrity Guardrails

1. Strict Multi-Tenancy Partitioning:
   • HubStaffAccount.Tenantid: nil designates Doormile internal operations staff (universal visibility); integer values strictly isolate partner tenant staff to their own organization's freight.
2. Rate-Limiting & PIN Brute-Force Defense:
   • authLimiter() throttles 4-digit PIN verification across /login, /verify-pin, and /reset-pin to a shared ceiling of 10 requests/minute per IP.
3. Idempotency on Financial & State Mutations:
   • POST /bookings/:id/payment, POST /pickup-complete, and POST /consignments/:id/deliver enforce Idempotency-Key headers backed by Redis to prevent double COD collection or duplicate consignment creation over flaky mobile connections.
4. Presigned Cloud Uploads:
   • Proof-of-delivery signatures and package photos are uploaded directly to cloud storage via time-limited presigned URLs (/miler/uploads/sign), ensuring storage secrets are never exposed on client devices.
5. Secure Receiver OTP Verification:
   • Delivery verification codes (deliveryotp) are issued exclusively to consignees and stripped from all rider and console APIs to prevent false deliveries.