266 lines
24 KiB
Markdown
266 lines
24 KiB
Markdown
# 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.
|