# 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 ```mermaid 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.