System Architecture

flowchart TB
  subgraph Clients["Client surfaces (Flutter + Web)"]
    PA["📱 Partner app"]
    BA["📱 Book app"]
    DA["📱 Dispatch / Hub"]
    WEB["💻 Next.js PWA
web booking + admin"]
    WA["💬 WhatsApp bot / IVR"]
  end

  subgraph Edge["Cloudflare edge"]
    CF["CDN · WAF · DNS
Workers (auth precheck, cache, rate-limit)"]
    R2["R2 object store
POD photos · KYC docs (no egress fee)"]
  end

  subgraph Core["Go backend (modular monolith)"]
    GW["API gateway / BFF
REST + WebSocket"]
    AUTH["Auth + KYC module"]
    BOOK["Booking + state machine"]
    MATCH["Matching engine"]
    GEO["Geo + routing"]
    PAY["Payments + escrow + ledger"]
    NOTIF["Notifications"]
    FRAUD["Fraud / trust scoring"]
  end

  subgraph Data["Data stores"]
    PG["🐘 PostgreSQL + PostGIS
(ACID core, ledger, geo)"]
    REDIS["⚡ Redis
live locations · ETA · surge · queues"]
  end

  subgraph Ext["Third-party"]
    RZP["Razorpay (primary)"]
    CFP["Cashfree (fallback + Easy KYC)"]
    VAHAN["VAHAN / Sarathi"]
    MAPS["Maps + OSRM"]
    SMS["SMS / IVR / WhatsApp API"]
    FCM["FCM push"]
  end

  PA & BA & DA & WEB --> CF
  WA --> NOTIF
  CF --> GW
  CF --- R2
  GW --> AUTH & BOOK & MATCH & GEO & PAY & NOTIF & FRAUD
  AUTH --> CFP & VAHAN
  PAY --> RZP & CFP
  GEO --> MAPS
  NOTIF --> SMS & FCM
  Core --> PG & REDIS
  classDef e fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  classDef c fill:#e7f4ec,stroke:#1b7f4b,color:#115c36;
  classDef d fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  class CF,R2 e; class GW,AUTH,BOOK,MATCH,GEO,PAY,NOTIF,FRAUD c; class PG,REDIS d;
        

erDiagram
  USER ||--o| PARTNER_PROFILE : has
  USER ||--o{ BOOKING : books
  PARTNER_PROFILE ||--o{ VEHICLE : owns
  PARTNER_PROFILE ||--o{ KYC_DOCUMENT : submits
  PARTNER_PROFILE }o--o{ RIDECHAIN_POINT : serves
  BOOKING ||--|{ PARCEL : contains
  BOOKING ||--|{ LEG : "splits into"
  LEG }o--|| PARTNER_PROFILE : "assigned to"
  LEG }o--o| RIDECHAIN_POINT : "from/to"
  BOOKING ||--|| PAYMENT : "paid by"
  PAYMENT ||--|{ ESCROW_LEDGER : records
  LEG ||--o| PAYOUT : "releases"
  BOOKING ||--o{ RATING : rated
  BOOKING ||--o{ FRAUD_SIGNAL : flags
  USER {
    uuid id
    string phone
    enum role
    string lang
  }
  BOOKING {
    uuid id
    enum status
    enum pickup_mode
    enum drop_mode
    enum speed_tier
    int total_fare_paise
  }
  PARCEL {
    enum category
    enum size_bucket
    enum weight_bucket
    int declared_value_paise
    bool fragile
  }
  LEG {
    int seq
    enum status
    string pickup_otp
    string drop_otp
    int payout_paise
  }
  ESCROW_LEDGER {
    uuid id
    enum entry_type
    int amount_paise
    string gateway_ref
  }
        

sequenceDiagram
  autonumber
  participant App as Book app
  participant CF as Cloudflare edge
  participant GW as Go API
  participant PR as Pricing
  participant PAY as Payments
  participant MA as Matching
  participant PT as Partner app
  App->>CF: POST /bookings (params)
  CF->>GW: forward (auth prechecked)
  GW->>PR: quote(size,weight,vehicle,geo,tier)
  PR-->>GW: fare + breakdown
  GW->>PAY: create escrow order (Razorpay → fallback Cashfree)
  PAY-->>App: payment intent
  App->>PAY: pay (UPI/wallet)
  PAY-->>GW: webhook: captured (idempotent)
  GW->>MA: dispatch (bundling-first → on-demand)
  MA->>PT: offer leg(s)
  PT-->>MA: accept
  MA-->>App: partner + ETA (live track begins)