diff --git a/apps/edr-freight-api/docs/FREIGHT_FLOW_VARIANTS.md b/apps/edr-freight-api/docs/FREIGHT_FLOW_VARIANTS.md new file mode 100644 index 000000000..53c8b76c3 --- /dev/null +++ b/apps/edr-freight-api/docs/FREIGHT_FLOW_VARIANTS.md @@ -0,0 +1,604 @@ +# EDR Freight — Major Flow Variants (each self-contained) + +The single master graph lives in [`FREIGHT_MASTER_FLOW.md`](./FREIGHT_MASTER_FLOW.md). This file breaks the +business logic into **one comprehensive, self-contained diagram per major scenario**, each organised with +phase **subgraphs** so it can be read on its own. + +**Axes covered** + +| Axis | Values | +| --------------- | -------------------------------------------------------------------------------------------- | +| Origin | **One-time booking** · **General contract** (Path A transport-only / Path B GENERAL+customs) | +| Trade direction | **Export** · **Import** · **Intercity / Domestic** | +| Customs | **With customs** · **Without customs** | + +**Legend** — (P) Portal (customer) · (B) Backoffice (staff) · (sys) System/event · (green) rounded = success end · (red) rounded = fail end · <> decision. + +**Which diagram do I read?** + +```mermaid +flowchart LR + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef box fill:#e0e7ff,stroke:#3730a3,color:#111 + A{"Origin?"}:::dec + A -->|"one-time"| B{"Trade direction?
(gate is direction-driven, NOT a customs toggle)"}:::dec + A -->|"framework agreement"| C{"Contract type?"}:::dec + B -->|"DOMESTIC"| D1["§1 One-time · DOMESTIC (no gate)"]:::box + B -->|"IMPORT / EXPORT
(with or without customs)"| D2["§2 One-time · IMPORT/EXPORT (gate)"]:::box + C -->|"transport-only (self-clearance)"| D3["§3 Contract · Path A"]:::box + C -->|"GENERAL + customs"| D4["§4 Contract · Path B"]:::box + D1 --> E{"Physical direction?"}:::dec + D2 --> E + D3 --> E + D4 --> E + E -->|"export"| F5["§5 EXPORT operations"]:::box + E -->|"import"| F6["§6 IMPORT operations"]:::box + E -->|"domestic"| F7["§7 INTERCITY operations"]:::box +``` + +> **How the two halves connect:** §1–§4 are the **commercial** journeys (intake → approval → contract → +> clearance → operation → payment). §5–§7 are the **physical** journeys (mile legs → warehouse → train → +> delivery). A shipment = one commercial variant **+** one physical variant. Each diagram fully details its +> own half and summarises the other so it stands alone. + +--- + +## §1 — One-time booking · DOMESTIC (no clearance gate) + +The commercial lifecycle when the counter-sign gate resolves to **no clearance** — which, in code, means +**trade direction = DOMESTIC** (not a customs toggle). Counter-sign goes straight to `FULLY_EXECUTED` and the +booking is enqueued **directly into the scheduling batch pipeline, skipping the operation-request/clearance +phase**. NOTE: Import/export bookings — _even with customs off_ — do **not** land here; they always hit the +clearance gate (§2, just with a lighter "without customs" document set). + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Company ACTIVE (approved profile)"]):::sys + + subgraph DRAFT["1 · Create & price"] + direction TB + d1["POST /bookings → DRAFT
reference, containers, cargo modifiers, files (P)"]:::port + d2["POST /bookings/:id/generate-price
rule-engine: LIVE rates + surcharges (P)"]:::port + dW{"weight-limit-rules"}:::dec + dWx(["HARD BLOCK 400 — VGM > capacity"]):::bad + d3["POST /bookings/:id/submit → SUBMITTED
freeze booking_rate_snapshot (P)"]:::port + dP{"price moved?"}:::dec + d3c["confirm-submit → SUBMITTED (P)"]:::port + d1 --> d2 --> dW + dW -->|"over capacity"| dWx + dW -->|"ok / warn+surcharge"| d3 --> dP + dP -->|"yes"| d3c + dP -->|"no"| out1 + d3c --> out1 + d1 -.->|"delete draft"| ddx(["removed"]):::bad + d3 -.->|"reject price"| drx(["REJECTED"]):::bad + end + out1[" "]:::sys + + subgraph INTAKE["2 · Staff intake & approval"] + direction TB + g{"government?"}:::dec + gexp["governmentExpedite → PAID + Eligible (B)"]:::back + i{"staff/accept | request-changes | reject (B)"}:::dec + ir["CHANGES_REQUESTED (B)"]:::back + irx(["REJECTED"]):::bad + ia["→ PENDING_APPROVAL
instantiate approval steps + validity window (B)"]:::back + ac{"chain: LINE_STAFF → DIRECTOR → CEO (B)"}:::dec + acx(["rejectStep → REJECTED"]):::bad + g -->|"yes"| gexp + g -->|"no"| i + i -->|"request-changes"| ir + i -->|"reject"| irx + i -->|"accept"| ia --> ac + ac -->|"rejectStep"| acx + end + + subgraph SIGN["3 · Contract doc & sign (DOMESTIC → no gate)"] + direction TB + s1["contract/generate → CONTRACT_READY (B)"]:::back + s2["customer sign → SIGNED_CUSTOMER (P)"]:::port + s3["staff counter-sign (DOMESTIC) → FULLY_EXECUTED
enqueueScheduleProcessing (no op-request) (B)(sys)"]:::back + s1 --> s2 --> s3 + end + + subgraph OPPAY["4 · Batch pipeline & payment"] + direction TB + fe["FULLY_EXECUTED enters day batch pool (sys)"]:::sys + b1["batch engine offers wagons → SELECTED_FOR_BATCH
invoice generated (sys)"]:::sys + p1["customer pays → gateway → PAID (P)"]:::port + pexp(["pay window lapses → reservation EXPIRED"]):::bad + fe --> b1 --> p1 + p1 -.->|"unpaid"| pexp + end + + phys(["Physical execution:
§7 intercity → COMPLETED (done)"]):::good + + pre --> DRAFT + out1 --> INTAKE + ac -->|"APPROVED"| SIGN + SIGN --> OPPAY + p1 --> phys + gexp -.->|"gov → PAID/Eligible"| phys +``` + +> **Road-mode note:** a domestic booking billed by road (truck) instead of rail goes through +> `operation/review` → `ROAD_DISPATCH_PENDING` (the road branch shown in the master graph), not the rail +> batch pool above. + +--- + +## §2 — One-time booking · IMPORT / EXPORT (clearance gate) + +Every IMPORT/EXPORT one-time booking traverses the clearance gate — **whether or not customs is enabled** +(the customs flag only selects a heavier vs lighter `clearance_*` document set; both go through +`AWAITING_DOCUMENTS`). Commercial spine as §1 (phases 1–3) **plus** the gate: counter-sign → `AWAITING_DOCUMENTS` +→ document review loop → `CLEARANCE_READY`, phased ET/DJ actions, then operation-request → payment. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + a0(["Booking APPROVED & signed by customer
(see §1 phases 1–3)"]):::sys + + subgraph CS["Counter-sign with customs"] + direction TB + cs1["staff counter-sign (IMPORT/EXPORT) → AWAITING_DOCUMENTS (B)"]:::back + end + + subgraph DOCS["5 · Document clearance gate"] + direction TB + x1["customer clearance/documents
→ DOCUMENTS_UNDER_REVIEW (P)"]:::port + x2{"GL clearance/review each doc (B)"}:::dec + x2q["doc Queried → customer re-uploads (B)"]:::back + x3["clearance/finalize (100% approved) → CLEARANCE_READY (B)"]:::back + x1 --> x2 + x2 -->|"query"| x2q --> x1 + x2 -->|"approve all"| x3 + end + + subgraph PHASED["6 · Phased ET / DJ clearance (as applicable)"] + direction TB + ph1["upload declaration (serial) (B)"]:::back + ph2["duty/tax advise → customer duty-slip (P)(B)"]:::back + ph3["transit permit (ET) (B)"]:::back + ph4["delivery order / release order (DJ) (B)"]:::back + ph5["T1 docs → T1 close (B)"]:::back + ph6["export release / finalize-pre-clearance (B)"]:::back + ph1 --> ph2 --> ph3 --> ph4 --> ph5 --> ph6 + end + + subgraph OPPAY2["7 · Operation request & payment"] + direction TB + o1["clearance/proceed → OPERATION_REQUEST_PENDING (P)"]:::port + o2{"operation/review (B)"}:::dec + o2c["OPERATION_CHANGES_REQUESTED (B)"]:::back + om{"mode?"}:::dec + ot["accept=train: invoice → FULLY_EXECUTED
→ batch offer → SELECTED_FOR_BATCH (B)(sys)"]:::back + orr["accept=road: invoice → ROAD_DISPATCH_PENDING (B)"]:::back + p1["customer pays → PAID (sys)(P)"]:::sys + pexp(["pay window lapses → EXPIRED"]):::bad + o1 --> o2 + o2 -->|"request-changes"| o2c --> o1 + o2 -->|"accept"| om + om -->|"train"| ot --> p1 + om -->|"road"| orr --> p1 + p1 -.->|"unpaid"| pexp + end + + cancel(["CANCELLED — staff-only, only from
OPERATION_REQUEST_PENDING here (not from
AWAITING_DOCUMENTS / DOCUMENTS_UNDER_REVIEW)"]):::bad + phys(["Physical execution:
§5 export · §6 import → COMPLETED (done)"]):::good + + a0 --> CS --> DOCS + x3 --> PHASED + ph6 --> OPPAY2 + p1 --> phys + o1 -.->|"cancel"| cancel +``` + +--- + +## §3 — General contract · Path A (transport-only, self-clearance) + +Framework agreement where the customer clears customs independently. After the contract is active and +operations verify self-clearance (`SELF_CLEARED`), the **customer books directly** under the contract; each +booking then runs the operation/payment/physical flow. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Company ACTIVE"]):::sys + + subgraph CTR["1 · Contract lifecycle"] + direction TB + c1["POST /contracts → DRAFT
routes + cargo scope + unit rates (NO quantities) (P)"]:::port + c2["generate-price → submit → SUBMITTED
freeze contract_rate_snapshots (P)"]:::port + c3{"staff/accept | request-changes | reject (B)"}:::dec + c3r["CHANGES_REQUESTED (B)"]:::back + c3x(["Contract REJECTED"]):::bad + c4["→ PENDING_APPROVAL (B)"]:::back + c4a{"approval chain (B)"}:::dec + c4x(["rejectStep → REJECTED"]):::bad + c5["generate-contract → CONTRACT_READY (B)"]:::back + c6["customer sign → SIGNED_CUSTOMER (P)"]:::port + c7["staff counter-sign (IMPORT/EXPORT self-clearance) →
AWAITING_CLEARANCE_DOCUMENTS (B)"]:::back + c1 --> c2 --> c3 + c3 -->|"request-changes"| c3r --> c2 + c3 -->|"reject"| c3x + c3 -->|"accept"| c4 --> c4a + c4a -->|"reject"| c4x + c4a -->|"approve"| c5 --> c6 --> c7 + c7 -.->|"lapse"| cexp(["EXPIRED"]):::bad + c7 -.->|"renew"| cren(["RENEWAL_DRAFT → new cycle"]):::bad + end + + subgraph SELF["2 · Self-clearance verification"] + direction TB + o1["customer uploads self-clearance docs (P)"]:::port + o2{"ops-review each doc (B)"}:::dec + o2q["query → re-upload (B)"]:::back + o3["ops-finalize → clearanceStatus SELF_CLEARED (B)"]:::back + o1 --> o2 + o2 -->|"query"| o2q --> o1 + o2 -->|"approve"| o3 + end + + subgraph BK["3 · Book directly under contract"] + direction TB + b1["customer POST /contracts/:id/bookings (P)"]:::port + bv{"validate-shipment:
window + capacity draw-down + pairing"}:::dec + bvx(["rejected: over capacity /
20ft pairing hard-block"]):::bad + b2["Booking created under contract
(bookings.contract_id) (sys)"]:::sys + b1 --> bv + bv -->|"fail"| bvx + bv -->|"ok"| b2 + end + + op(["Booking runs operation + payment
(see §1 phase 4) then §5/§6/§7 → COMPLETED (done)"]):::good + + pre --> CTR + c7 --> SELF + o3 --> BK + b2 --> op +``` + +--- + +## §4 — General contract · Path B (GENERAL + customs) + +Framework agreement **with** customs. The customer cannot book directly — they submit a **BookingRequest** +(date + quantities only); GL Ethiopia accepts it and creates the booking, which then runs **per-booking +phased customs** on the `/contracts/bookings/:bookingId/*` surface. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Company ACTIVE"]):::sys + + subgraph CTR["1 · Contract lifecycle (customs)"] + direction TB + c1["POST /contracts → DRAFT → submit → approve → sign (P)(B)"]:::port + c7["staff counter-sign (GENERAL + customs) → CONTRACT_ACTIVE
(contract clearance cycle SKIPPED — runs per-booking) (B)"]:::back + c1 --> c7 + c1 -.->|"reject / lapse"| cx(["REJECTED / EXPIRED"]):::bad + end + + subgraph REQ["2 · Booking request → GL creates booking"] + direction TB + r1["customer POST /contracts/:id/booking-requests
(date + quantities, no per-unit data) (P)"]:::port + r2{"GL booking-request queue (B)"}:::dec + r2x(["reject / customer cancel →
REJECTED / CANCELLED"]):::bad + r3["GL accept → GL creates booking under contract
(ct:create_booking) (B)"]:::back + r1 --> r2 + r2 -->|"reject/cancel"| r2x + r2 -->|"accept"| r3 + end + + subgraph GLC["3 · Per-booking GL clearance & milestones"] + direction TB + g1["station-assign (route + bind staff) (B)"]:::back + g2["declaration → duty advise (GREEN/YELLOW/RED risk) (B)"]:::back + g3["customer duty-slip → transit / delivery / release order (P)(B)"]:::back + g4["T1 docs → T1 close (B)"]:::back + g5["final-invoice → customer slip → confirm paid (P)(B)"]:::back + g6["second-duty (post-arrival import) → slip (P)(B)"]:::back + gi["incident reports (photos) as needed (B)"]:::back + g1 --> g2 --> g3 --> g4 --> g5 --> g6 + g4 -.-> gi + end + + op(["Booking runs operation + payment (see §1 phase 4)
then §5/§6 physical → COMPLETED (done)"]):::good + + pre --> CTR + c7 --> REQ + r3 --> GLC + g6 --> op +``` + +--- + +## §5 — EXPORT operations (physical execution) + +Given a PAID, scheduled **export** booking: optional first-mile road leg → origin warehouse inbound → train +build & dispatch → corridor transit → Djibouti port unload → interchange handover. Cargo leaves the country +at the port; the booking's terminal here is **dispatched/handed-over at Djibouti**. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Export booking PAID & Eligible
(see §1/§2/§3/§4)"]):::sys + + subgraph FM["1 · First-mile (if EXPORT + requested)"] + direction TB + fmq{"first-mile requested?"}:::dec + fm1["leg auto-created firstMile.acceptBooking
READY_TO_TRANSIT (sys)"]:::sys + fm2["setVehicles → vehicle BUSY, SMS driver, fleet_events (B)"]:::back + fm3["IN_TRANSIT (needs vehicle) → RECEIVED_TO_PORT (B)"]:::back + fm4["first-mile invoice (FIRST_MILE fee); distances lock once invoiced (B)"]:::back + fmq -->|"yes"| fm1 --> fm2 --> fm3 --> fm4 + fmq -->|"no"| fmskip[" "]:::sys + end + + subgraph WH["2 · Origin warehouse inbound"] + direction TB + w1["receive / bulkReceive → RECEIVED
capacity assert, GRN, notify owner SMS (B)"]:::back + w2{"inspection"}:::dec + w2f["FAILED / NEEDS_REVIEW → hold + re-inspect (B)"]:::back + w3["store (allocation rule → yard/zone) → STORED (B)"]:::back + w4["reserve (booking PAID) → RESERVED (B)"]:::back + w5["mark-ready-for-loading (inspection PASSED) → READY_FOR_LOADING (B)"]:::back + w6["load onto wagon → LOADED (+ warehouse_loadings) (B)"]:::back + w1 --> w2 + w2 -->|"fail"| w2f --> w2 + w2 -->|"PASSED"| w3 --> w4 --> w5 --> w6 + end + + subgraph SCHED["3 · Train build & schedule"] + direction TB + s1["schedule DRAFT (≥2 locos, derive EXPORT direction) (B)"]:::back + s2["assign-bookings + run-allocation (wagons) (B)"]:::back + s3["pin wagons → finalize → SCHEDULED (bookings Scheduled) (B)"]:::back + s3x["cancel schedule → bookings Eligible (B)"]:::back + s1 --> s2 --> s3 + s3 -.->|"cancel"| s3x -.-> s1 + s3 -.->|"gov preempt / maintenance"| sr["reschedule: retained/displaced/readmitted (B)"]:::back + sr -.-> s2 + end + + subgraph RUN["4 · Dispatch → Djibouti"] + direction TB + r1["dispatch → DISPATCHED
train_number, locos ASSIGNED, window CLOSED, unpaid EXPIRED (B)"]:::back + r2["checkpoints (corridor) → train_checkpoint_events (B)"]:::back + rc["customer tracking page GET /tracking/:id (JWT) (P)
NOTE: tracking_events has no writer — timeline empty"]:::port + r3["arrive → ARRIVED (bookings IN_TRANSIT, wagons/locos freed) (B)"]:::back + ru["export/auto-unload-at-djibouti →
UNLOADED_AT_DJIBOUTI_PORT (B)"]:::back + ri["interchange document generate-from-schedule → GENERATED (B)"]:::back + ria{"port acknowledges?"}:::dec + r1 --> r2 --> r3 --> ru --> ri --> ria + r2 -.-> rc + end + + done(["Export dispatched & handed over at Djibouti (done)"]):::good + disp(["interchange DISPUTED → remarks / re-issue"]):::bad + + pre --> FM + fm4 --> WH + fmskip --> WH + w6 --> SCHED + s3 --> RUN + ria -->|"acknowledge"| done + ria -->|"dispute"| disp +``` + +--- + +## §6 — IMPORT operations (physical execution) + +Given a PAID, scheduled **import** booking arriving by train from Djibouti: destination warehouse unload → +inspection → import customs finalization → optional last-mile → fee gate-clearance → release → delivery → +**COMPLETED**. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Import booking PAID & scheduled
(see §1/§2/§4)"]):::sys + + subgraph RAIL["1 · Import train arrival"] + direction TB + t1["import train dispatched from Djibouti → DISPATCHED (B)"]:::back + t2["checkpoints → train_checkpoint_events (B)"]:::back + tc["customer tracking page GET /tracking/:id (JWT) (P)
NOTE: tracking_events has no writer — timeline empty"]:::port + t3["arrive → ARRIVED (bookings IN_TRANSIT) → warehouse arrival automation (B)"]:::back + t1 --> t2 --> t3 + t2 -.-> tc + end + + subgraph WH["2 · Destination warehouse"] + direction TB + w1["import/auto-unload-arrived-bookings (assign WH/yard/zone) → UNLOADED (B)"]:::back + w2{"inspection PASSED?"}:::dec + w2f["FAILED → hold / re-inspect / djibouti-incident report (B)"]:::back + w3["→ READY_FOR_PICKUP (IMPORT) (B)"]:::back + w1 --> w2 + w2 -->|"no"| w2f --> w2 + w2 -->|"yes"| w3 + end + + subgraph CUST["3 · Import customs finalization (timestamp-driven)"] + direction TB + u1["upload docs (IM4/IM5/T1_CLOSURE/TRANSIT_PERMIT/…) (B)"]:::back + u2["record declaration serial (B)"]:::back + u3["notify duties/taxes (B)"]:::back + u4["mark duties paid (needs CUSTOMER_PAYMENT_SLIP) (B)"]:::back + u5["assign risk (GREEN/YELLOW/BLUE/RED) (B)"]:::back + u6{"release gates satisfied?
T1 + release permit + declaration + risk + paid"}:::dec + u6x["blocked — missing gate → resolve (B)"]:::back + u7["release-permitted → completedAt (B)"]:::back + u1 --> u2 --> u3 --> u4 --> u5 --> u6 + u6 -->|"no"| u6x --> u6 + u6 -->|"yes"| u7 + end + + subgraph LM["4 · Last-mile (if requested)"] + direction TB + lq{"last-mile requested?"}:::dec + l1["leg auto-created lastMile.acceptBooking
READY_TO_TRANSIT (sys)"]:::sys + l2["setVehicles → IN_TRANSIT → DELIVERED (free vehicles) (B)"]:::back + l3["last-mile invoice (LAST_MILE fee) (B)"]:::back + lq -->|"yes"| l1 --> l2 --> l3 + lq -->|"no"| lskip[" "]:::sys + end + + subgraph DEL["5 · Release & delivery"] + direction TB + d0{"warehouse/storage fees fully PAID?"}:::dec + d0x["gate-clearance BLOCKED (findBlockingInvoice) (B)"]:::back + d0p["customer pays storage/demurrage online (P)"]:::port + d1["release order (DO) + gate-clearance → deliver (B)"]:::back + d2["customer approve-delivery (saved signature) → POD (P)"]:::port + d3["inventory DELIVERED, POD to cargo, container freed (sys)"]:::sys + d0 -->|"no"| d0x --> d0p --> d0 + d0 -->|"yes"| d1 --> d2 --> d3 + end + + ecr(["empty-container-return chain (post-import):
RETURNED → … → HANDOVER_ISSUED → COMPLETED"]):::sys + done(["Booking COMPLETED (done) (operations/complete)"]):::good + + pre --> RAIL + t3 --> WH + w3 --> CUST + u7 --> LM + l3 --> DEL + lskip --> DEL + d3 --> done + done -.-> ecr +``` + +--- + +## §7 — INTERCITY / DOMESTIC operations (no cross-border customs) + +Rail movement **between Ethiopian yards** (e.g. inland dry ports). No import/export customs, no Djibouti +port unload or interchange handover. Optional road mile legs if the service includes door delivery. + +```mermaid +flowchart TD + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + pre(["Domestic booking PAID & Eligible
(see §1 — customs OFF)"]):::sys + + subgraph FMD["1 · Optional origin pickup (road)"] + direction TB + fq{"door pickup / first-mile requested?"}:::dec + f1["first-mile leg → vehicle assign → RECEIVED_TO_PORT (B)"]:::back + fq -->|"yes"| f1 --> fnext[" "]:::sys + fq -->|"no (drop at origin yard)"| fnext + end + + subgraph WHO["2 · Origin warehouse"] + direction TB + w1["receive → RECEIVED (B)"]:::back + w2{"inspection PASSED?"}:::dec + w2f["hold + re-inspect (B)"]:::back + w3["store → STORED → reserve (PAID) → RESERVED (B)"]:::back + w4["ready-for-loading → LOADED onto wagon (B)"]:::back + w1 --> w2 + w2 -->|"no"| w2f --> w2 + w2 -->|"yes"| w3 --> w4 + end + + subgraph RUN["3 · Train (ET yard → ET yard)"] + direction TB + s1["schedule DRAFT (direction DOMESTIC) → assign → finalize → SCHEDULED (B)"]:::back + r1["dispatch → DISPATCHED (unpaid EXPIRED) (B)"]:::back + r2["checkpoints → train_checkpoint_events; customer tracking (JWT) (P)(B)"]:::back + r3["arrive → ARRIVED (bookings IN_TRANSIT) (B)"]:::back + s1 --> r1 --> r2 --> r3 + end + + subgraph WHD["4 · Destination warehouse & delivery"] + direction TB + d1["auto-unload arrived → UNLOADED / RECEIVED (B)"]:::back + di{"inspection PASSED?"}:::dec + dif["hold + re-inspect (B)"]:::back + d2["READY_FOR_PICKUP (B)"]:::back + fee{"storage fees paid?"}:::dec + feex["gate-clearance blocked → customer pays (P)"]:::port + d3["release order → deliver (B)"]:::back + lq{"door delivery / last-mile?"}:::dec + l1["last-mile leg → DELIVERED (B)"]:::back + d4["customer approve-delivery → POD → inventory DELIVERED (P)(sys)"]:::sys + d1 --> di + di -->|"no"| dif --> di + di -->|"yes"| d2 --> fee + fee -->|"no"| feex --> fee + fee -->|"yes"| d3 --> lq + lq -->|"yes"| l1 --> d4 + lq -->|"no (pickup at yard)"| d4 + end + + done(["Booking COMPLETED (done)"]):::good + + pre --> FMD + fnext --> WHO + w4 --> RUN + r3 --> WHD + d4 --> done +``` + +--- + +## Cross-reference + +| Variant | Distinctive gate(s) | Terminal ends unique to it | +| --------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| §1 One-time · DOMESTIC | counter-sign → `FULLY_EXECUTED` (skips clearance **and** op-request; enters batch directly) | HARD BLOCK, price/intake/approval REJECTED, EXPIRED | +| §2 One-time · IMPORT/EXPORT | `AWAITING_DOCUMENTS` → review loop → phased ET/DJ → op-request (gate applies with **or without** customs) | + doc-query loop, CANCELLED (only from OPERATION_REQUEST_PENDING) | +| §3 Contract · Path A | `SELF_CLEARED` via ops-review; customer books direct | contract REJECTED/EXPIRED/RENEWAL, capacity/pairing block | +| §4 Contract · Path B | BookingRequest → GL creates booking; per-booking milestones | BookingRequest REJECTED/CANCELLED | +| §5 Export ops | first-mile → Djibouti unload → interchange handover | dispatched@Djibouti (success), interchange DISPUTED | +| §6 Import ops | import customs finalization gates → last-mile → gate-clearance | COMPLETED (+ empty-container-return chain) | +| §7 Intercity ops | ET→ET rail, no cross-border customs, optional mile legs | COMPLETED | + +Full endpoint tables & per-domain state machines: [`FREIGHT_SYSTEM_FLOW.md`](./FREIGHT_SYSTEM_FLOW.md). +Single all-in-one branching graph: [`FREIGHT_MASTER_FLOW.md`](./FREIGHT_MASTER_FLOW.md). diff --git a/apps/edr-freight-api/docs/FREIGHT_MASTER_FLOW.md b/apps/edr-freight-api/docs/FREIGHT_MASTER_FLOW.md new file mode 100644 index 000000000..ea68e6938 --- /dev/null +++ b/apps/edr-freight-api/docs/FREIGHT_MASTER_FLOW.md @@ -0,0 +1,260 @@ +# EDR Freight — One Master Flow (signup → every end) + +Single comprehensive graph of the entire freight business logic: from customer signup through every +branch to every terminal state. Actor-coloured, endpoint-labelled. + +**Legend** +(P) Portal (customer) · (B) Backoffice (staff) · (sys) System/auto (event, cron, service-to-service) +Rounded green = success end · Red = failure/terminal end · Diamond = decision · Hexagon = domain event. + +```mermaid +flowchart TD + classDef start fill:#e0e7ff,stroke:#3730a3,color:#111 + classDef port fill:#dbeafe,stroke:#2563eb,color:#111 + classDef back fill:#fef3c7,stroke:#b45309,color:#111 + classDef sys fill:#dcfce7,stroke:#15803d,color:#111 + classDef dec fill:#f8fafc,stroke:#475569,color:#111 + classDef good fill:#86efac,stroke:#166534,color:#062e14 + classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a + + %% ================= PHASE 1: IDENTITY & ONBOARDING ================= + S0(["Customer visits portal"]):::start + S0 --> S1["Signup via IAM
GET /auth/check-availability @Public
POST /otp/send + /otp/verify (P)"]:::port + S1 --> S2{"Identity proofing
(VeriFayda)?"}:::dec + S2 -->|"Yes"| S3["POST /fayda/verification/start →
/callback → /complete
upsert iam.users (verified_by=fayda) (P)"]:::port + S2 -->|"No"| S4 + S3 --> S4["POST /companies/onboarding/start
draft company (placeholder TIN, PENDING) (P)"]:::port + S4 --> S4b["Wizard: PATCH /profile, /onboarding-step,
upload license + docs
GET /onboarding/requirements (P)"]:::port + S4b --> S5["POST /companies/onboarding/complete
re-validate → company+profiles = PENDING (P)"]:::port + S5 --> S6{"Backoffice reviews profile
PATCH /company-profiles/:id/status (B)"}:::dec + S6 -->|"Reject / suspend"| S6x(["SUSPENDED / BLACKLISTED
cannot transact"]):::bad + S6 -->|"Approve"| S7["Mint reference (EX-#####),
company → ACTIVE (B)"]:::back + S7 --> S8{"Start a shipment?"}:::dec + S8 -->|"idle"| S8x(["No booking (dormant account)"]):::bad + S8 -->|"Yes"| MODE + + %% ================= PHASE 2: COMMERCIAL ORIGIN ================= + MODE{"Booking origin?"}:::dec + MODE -->|"One-time shipment"| B0 + MODE -->|"Framework agreement"| C1 + + %% ---- Contract track ---- + C1["Create CONTRACT DRAFT
POST /contracts (routes + cargo scope) (P)"]:::port + C1 --> C1d{"Abandon draft?"}:::dec + C1d -->|"delete"| C1x(["Contract removed (soft-delete)"]):::bad + C1d -->|"continue"| C2["generate-price → submit → SUBMITTED
freeze contract_rate_snapshots (P)"]:::port + C2 --> C2p{"Price changed?"}:::dec + C2p -->|"Yes"| C2c["confirm-submit → SUBMITTED (P)"]:::port + C2p -->|"No"| C3 + C2c --> C3 + C3{"Staff intake
POST /contracts/:id/staff/* (B)"}:::dec + C3 -->|"request-changes"| C3r["CHANGES_REQUESTED (B)"]:::back + C3r -->|"edit + resubmit"| C2 + C3 -->|"reject"| C3x(["Contract REJECTED"]):::bad + C3 -->|"accept"| C4["→ PENDING_APPROVAL
instantiate approval steps (B)"]:::back + C4 --> C4a{"Approval chain
line → director → ceo (B)"}:::dec + C4a -->|"rejectStep"| C4x(["Contract REJECTED"]):::bad + C4a -->|"all approve"| C5["generate-contract → CONTRACT_READY (B)"]:::back + C5 --> C6["Customer sign → SIGNED_CUSTOMER
POST /contracts/:id/contract/sign (P)"]:::port + C6 --> C7{"Staff counter-sign branch"}:::dec + C7 -->|"customs on"| C7a["AWAITING_CLEARANCE_DOCUMENTS (B)"]:::back + C7 -->|"GENERAL"| C7b["CONTRACT_ACTIVE (B)"]:::back + C7 -->|"ONE_TIME"| C7c["FULLY_EXECUTED (B)"]:::back + C7a --> CPATH + C7b --> CPATH + C7c --> CPATH + C7b -.->|"renew"| C7renew(["RENEWAL_DRAFT → new cycle"]):::bad + C7b -.->|"lapse"| C7exp(["Contract EXPIRED"]):::bad + + CPATH{"How are shipments booked
under the contract?"}:::dec + CPATH -->|"Path A: transport-only"| CPA["Ops review self-clearance
ops-review → ops-finalize → SELF_CLEARED (B)
then customer books direct
POST /contracts/:id/bookings (P)"]:::port + CPATH -->|"Path B: GENERAL + customs"| CPB["Customer submits BookingRequest
POST /contracts/:id/booking-requests (P)"]:::port + CPB --> CPBq{"GL queue decision (B)"}:::dec + CPBq -->|"reject / customer cancels"| CPBx(["BookingRequest REJECTED / CANCELLED"]):::bad + CPBq -->|"accept → GL creates booking"| B0u + CPA --> B0u["Booking created UNDER contract
(window + capacity draw-down check) (sys)"]:::sys + B0u --> BFLOW + + %% ---- One-time booking ---- + B0["Create BOOKING DRAFT
POST /bookings (reference, containers,
cargo modifiers, files) (P)"]:::port + B0 --> B0d{"Abandon draft?"}:::dec + B0d -->|"delete"| B0x(["Booking removed (soft-delete)"]):::bad + B0d -->|"continue"| BFLOW + B0 -.->|"consolidation"| BCONS(["PENDING_CONSOLIDATION
waits for partner shipment
(shares a wagon) → rejoins"]):::sys + BCONS -.-> BFLOW + + %% ================= PHASE 3: PRICING & SUBMIT ================= + BFLOW["Configure shipment
freight type + trade direction"]:::sys + BFLOW --> FT{"Freight type?"}:::dec + FT -->|"CONTAINER"| DIR + FT -->|"BULK"| DIR + DIR{"Trade direction?"}:::dec + DIR -->|"EXPORT"| B1 + DIR -->|"IMPORT"| B1 + DIR -->|"DOMESTIC"| B1 + B1["POST /bookings/:id/generate-price
rule-engine: LIVE rates + surcharges
HAZARDOUS / REEFER / OVERWEIGHT /
SHIPPING_LINE / CONSOLIDATION (P)"]:::port + B1 --> B1w{"weight-limit-rules check"}:::dec + B1w -->|"VGM > maxCapacity"| B1x(["HARD BLOCK (400)
cannot submit"]):::bad + B1w -->|"over maxVgm, within cap"| B1warn["warning + OVERWEIGHT surcharge"]:::sys + B1w -->|"ok"| B2 + B1warn --> B2 + B2["POST /bookings/:id/submit → SUBMITTED
create booking_rate_snapshot (P)"]:::port + B2 --> B2p{"Price moved since draft?"}:::dec + B2p -->|"Yes → PRICE_CHANGED_PENDING_CONFIRM"| B2c["confirm-submit → SUBMITTED (P)"]:::port + B2p -->|"No"| GOV + B2c --> GOV + B2 -.->|"customer rejects price"| B2x(["Booking REJECTED"]):::bad + + %% ================= PHASE 4: INTAKE & APPROVAL ================= + GOV{"Government booking?"}:::dec + GOV -->|"Yes"| GEXP["governmentExpedite →
PAID + schedulingStatus Eligible (B)"]:::back + GOV -->|"No (commercial)"| BI{"Staff intake
POST /bookings/:id/staff/* (B)"}:::dec + BI -->|"request-changes"| BIr["CHANGES_REQUESTED (B)"]:::back + BIr -->|"edit + resubmit"| B2 + BI -->|"reject"| BIx(["Booking REJECTED"]):::bad + BI -->|"accept"| BA["→ PENDING_APPROVAL
instantiate approval steps
(set validity window) (B)"]:::back + BA --> BAc{"Approval chain
LINE_STAFF → DIRECTOR → CEO (B)"}:::dec + BAc -->|"rejectStep"| BAx(["Booking REJECTED"]):::bad + BAc -->|"all approve → APPROVED"| BC1 + + %% ================= PHASE 5: CONTRACT DOC & SIGN ================= + BC1["contract/generate → CONTRACT_READY (B)"]:::back + BC1 --> BC2["Customer sign → SIGNED_CUSTOMER
POST /bookings/:id/contract/sign (P)"]:::port + BC2 --> BC3{"Staff counter-sign:
trade direction?"}:::dec + BC3 -->|"IMPORT / EXPORT
(clearance gate, even if customs off)"| CL1 + BC3 -->|"DOMESTIC"| FEXD["counter-sign → FULLY_EXECUTED
enqueue batch (skips clearance + op-request) (sys)(B)"]:::back + FEXD --> FEB + + %% ================= PHASE 6: CUSTOMS CLEARANCE ================= + CL1["AWAITING_DOCUMENTS → customer uploads
POST /bookings/:id/clearance/documents
→ DOCUMENTS_UNDER_REVIEW (P)"]:::port + CL1 --> CL2{"GL reviews each doc
clearance/review (B)"}:::dec + CL2 -->|"Query"| CL2q["doc queried → customer re-uploads (B)"]:::back + CL2q --> CL1 + CL2 -->|"Approve all"| CL3["finalize (100% approved) → CLEARANCE_READY (B)"]:::back + CL3 --> CLph["Phased ET/DJ (as applicable):
declaration → duty advise → duty slip →
transit permit → delivery/release order →
T1 docs/close → export release (sys)(B)"]:::back + CLph --> OP1 + + %% ================= PHASE 7: OPERATION REQUEST ================= + OP1["clearance/proceed: pick binding schedule day
→ OPERATION_REQUEST_PENDING (P)"]:::port + OP1 --> OP2{"Operations review
POST /bookings/:id/operation/review (B)"}:::dec + OP2 -->|"REQUEST_CHANGES"| OP2c["OPERATION_CHANGES_REQUESTED (B)"]:::back + OP2c --> OP1 + OP2 -->|"ACCEPT"| OPM{"Operation mode?"}:::dec + OPM -->|"TRAIN (rail)"| OP3t["invoice generated → FULLY_EXECUTED
(day batch pool) (B)"]:::back + OPM -->|"ROAD (truck)"| OP3r["invoice generated →
ROAD_DISPATCH_PENDING (billed by KM) (B)"]:::back + OP3t --> FEB["batch engine offers wagons →
SELECTED_FOR_BATCH (sys)"]:::sys + + %% ================= PHASE 8: INVOICE & PAYMENT ================= + GEXP --> SCH + FEB --> PAY1 + OP3r --> PAY1 + PAY1["Invoice (source=booking, INV-YYYYMMDD-#####, due +14d)
booking invoice starts DRAFT → ISSUED at operation-accept (sys)"]:::sys + PAY1 --> PAY2["Customer pays
POST /billing/my-invoices/:id/pay →
billing.payInvoice → payment-api initiate (P)"]:::port + PAY2 --> PAYp{"Provider result
(Telebirr/CBE/EBirr/Waafi/DMoney/Card/CAC)"}:::dec + PAYp -->|"FAILED"| PAYf["invoice stays OPEN (retry)"]:::sys + PAYf --> PAY2 + PAYp -->|"pay window lapses"| PAYexp(["Booking/reservation EXPIRED"]):::bad + PAYp -->|"SUCCEEDED"| PAYok["webhook → payment outbox →
POST /internal/payments/mark-paid →
settleByPaymentId → invoice PAID (sys)"]:::sys + PAYok --> EVT1{{"booking.invoice.paid event"}}:::sys + EVT1 --> PAID["Booking → PAID"]:::sys + PAYok -.->|"post-pay"| PAYref(["REFUNDED (terminal)"]):::bad + PAID --> FMQ0 + EVT1 -.->|"if EXPORT + first-mile"| FM1 + PAID --> SCH + + %% ================= PHASE 9: SCHEDULING & ALLOCATION ================= + SCH["schedulingStatus = Eligible (sys)"]:::sys + SCH --> SC2["Train schedule DRAFT
POST /train-scheduling/{container|bulk}/schedules
≥2 locomotives, derive direction (B)"]:::back + SC2 --> SC3["assign-bookings + run-allocation
(wagon_booking_allocations) (B)"]:::back + SC3 --> SC4["pin physical wagons → finalize → SCHEDULED
bookings → Scheduled (B)"]:::back + SC4 -.->|"cancel schedule"| SC4x["bookings back to Eligible (B)"]:::back + SC4x -.-> SC2 + SC4 -.->|"gov preempt / maintenance"| RESCH["reschedule: retained / displaced /
readmitted (priority: gov first) (B)"]:::back + RESCH -.-> SC3 + SC4 --> FMQ0 + + %% ================= PHASE 10: FIRST-MILE (export origin road leg) ================= + FMQ0{"EXPORT + first-mile requested?"}:::dec + FMQ0 -->|"Yes"| FM1["first-mile leg auto-created
firstMile.acceptBooking (READY_TO_TRANSIT) (sys)"]:::sys + FMQ0 -->|"No"| WO1 + FM1 --> FM2["setVehicles → vehicle BUSY, SMS driver,
fleet_events (B)"]:::back + FM2 --> FM3["IN_TRANSIT (needs vehicle) →
RECEIVED_TO_PORT (free vehicles) (B)"]:::back + FM3 --> FM4["first-mile invoice (FIRST_MILE fee) (B)"]:::back + FM4 --> WO1 + + %% ================= PHASE 11: WAREHOUSE ORIGIN (export) ================= + WO1["receive / bulkReceive → RECEIVED
capacity assert, GRN, notify owner (B)"]:::back + WO1 --> WO2{"inspection outcome"}:::dec + WO2 -->|"FAILED / NEEDS_REVIEW"| WO2f["hold + re-inspect (B)"]:::back + WO2f --> WO2 + WO2 -->|"PASSED"| WO3["store (allocation rule picks yard/zone) → STORED (B)"]:::back + WO3 --> WO4["reserve (booking PAID) → RESERVED (B)"]:::back + WO4 --> WO5["mark-ready-for-loading → READY_FOR_LOADING (B)"]:::back + WO5 --> WO6["load onto wagon → LOADED
(+ warehouse_loadings) (B)"]:::back + WO6 --> TR1 + + %% ================= PHASE 12: DISPATCH & TRANSIT ================= + TR1["dispatch → DISPATCHED
assign train_number, locos ASSIGNED,
window CLOSED, unpaid reservations EXPIRED (B)"]:::back + TR1 --> TR2["record checkpoints (corridor stations) →
train_checkpoint_events (B)"]:::back + TR2 --> TRC["Customer tracking page
GET /tracking/:consignmentId (JWT) (P)"]:::port + TR2 --> TR3["arrive (final checkpoint) → ARRIVED
bookings IN_TRANSIT, locos+wagons freed,
warehouse arrival automation (B)"]:::back + TR3 --> WD1 + + %% ================= PHASE 13: WAREHOUSE DEST + IMPORT CUSTOMS ================= + WD1["destination warehouse: auto-unload arrived
→ UNLOADED / RECEIVED (B)"]:::back + WD1 --> WD2{"inspection PASSED?"}:::dec + WD2 -->|"No"| WD2f["hold + re-inspect / incident report (B)"]:::back + WD2f --> WD2 + WD2 -->|"Yes"| DIRW{"trade direction at destination"}:::dec + DIRW -->|"IMPORT"| WD3["READY_FOR_PICKUP (B)"]:::back + DIRW -->|"EXPORT (Djibouti)"| WDX["auto-unload-at-djibouti → DISPATCHED /
UNLOADED_AT_DJIBOUTI_PORT (B)"]:::back + WD3 --> IMP1["Import customs finalization:
upload docs → declaration → notify duties →
duties paid (needs slip) → assign risk →
release-permitted (all gates) (sys)(B)"]:::back + IMP1 --> LMQ + WDX --> ICD["interchange document (handover manifest)
generate-from-schedule → GENERATED →
ACKNOWLEDGED / DISPUTED (B)"]:::back + ICD --> DE1 + + %% ================= PHASE 14: LAST-MILE (import destination road leg) ================= + LMQ{"IMPORT + last-mile requested?"}:::dec + LMQ -->|"Yes"| LM1["last-mile leg auto-created
(IMPORT inspection PASSED only) (sys)"]:::sys + LMQ -->|"No"| DE1 + LM1 --> LM2["setVehicles → IN_TRANSIT → DELIVERED
(free vehicles) (B)"]:::back + LM2 --> LM3["last-mile invoice (LAST_MILE fee) (B)"]:::back + LM3 --> DE1 + + %% ================= PHASE 15: DELIVERY & COMPLETION ================= + DE1{"Warehouse/storage fees fully PAID?"}:::dec + DE1 -->|"No"| DE1x["gate-clearance BLOCKED
findBlockingInvoice / assertClearanceAllowed (B)"]:::back + DE1x --> DE1p["Customer pays storage/demurrage
warehouse-fee-invoices/:id/pay-online (P)"]:::port + DE1p --> DE1 + DE1 -->|"Yes"| DE2["release order (DO) + gate-clearance →
deliver (B)"]:::back + DE2 --> DE3["Customer approves delivery (saved signature)
POST /warehouse-inventory/bookings/:id/approve-delivery (P)"]:::port + DE3 --> DE4["inventory DELIVERED, POD to cargo,
container freed, capacity released (sys)"]:::sys + DE4 --> DONE(["Booking COMPLETED (done)
operations/complete"]):::good + + %% ================= GLOBAL EXITS ================= + GEXIT(["CANCELLED — POST /bookings/:id/cancel (staff-only)
ONLY from DRAFT, SUBMITTED, PRICE_CHANGED_PENDING_CONFIRM,
CHANGES_REQUESTED, PENDING_APPROVAL, CONTRACT_READY,
OPERATION_REQUEST_PENDING"]):::bad + B2 -.->|"cancel"| GEXIT + BA -.->|"cancel"| GEXIT + OP1 -.->|"cancel"| GEXIT +``` + +--- + +## Reading notes + +- **Solid arrows** = the primary progression. **Dotted arrows** = optional / event-driven / exit hops + (consolidation, reschedule, cancel, the first-mile event branch). +- **Every terminal** is a rounded red or green node: + `SUSPENDED/BLACKLISTED`, `dormant`, `booking/contract removed`, `REJECTED` (customer price, staff intake, + approval step, GL booking-request), `HARD BLOCK` (VGM), `EXPIRED` (pay window / contract), `REFUNDED`, + `RENEWAL_DRAFT`, `CANCELLED`, and the single success end **`COMPLETED (done) `**. +- **Branch axes** captured: identity-proofing (Fayda / skip), origin (one-time vs contract Path A / Path B), + freight type (container / bulk), trade direction (import / export / domestic), customer type + (government expedite vs commercial approval chain), customs on/off, operation mode (rail / road), + provider outcome (success / fail-retry / expire / refund), first-mile (export), last-mile (import), + Djibouti export unload + interchange handover. +- **Actors**: (P) portal customer, (B) backoffice staff, (sys) system (events like `booking.invoice.paid`, + `warehouse.invoice.paid`, auto leg creation, payment webhook/outbox settlement). + +> Endpoint-level tables, per-domain state machines, and the payment-microservice sequence live in +> [`FREIGHT_SYSTEM_FLOW.md`](./FREIGHT_SYSTEM_FLOW.md). This file is the single end-to-end picture. diff --git a/apps/edr-freight-api/docs/FREIGHT_SYSTEM_FLOW.md b/apps/edr-freight-api/docs/FREIGHT_SYSTEM_FLOW.md new file mode 100644 index 000000000..a6fd8bbeb --- /dev/null +++ b/apps/edr-freight-api/docs/FREIGHT_SYSTEM_FLOW.md @@ -0,0 +1,872 @@ +# EDR Freight System — End-to-End Flow Map (FE → Backend) + +> Comprehensive flow documentation for the **Freight Management** slice of the EDR Platform: +> the two frontends (**Customer Portal** + **Backoffice**) and how every action reaches the +> **freight API**, the **payment microservice**, Postgres, MinIO and RabbitMQ. +> +> Generated by mapping all ~45 API modules (~300 routes / 60 controllers) against both FE apps. +> Layered on purpose: a **master business-flow** view first, then **per-domain endpoint-level** charts. + +--- + +## 0. How to read this document + +- **Master view** (§3) is the freight journey at business altitude — state transitions across domains. +- **Per-domain views** (§5–§13) drop to endpoint altitude — every `Method /path`, its guard, and the FE caller. +- Diagrams are [Mermaid](https://mermaid.js.org). GitHub / VS Code (Markdown Preview Mermaid) render them inline. +- **Legend** used throughout: + - (P) **Portal** = `@edr/freight-portal` (customer users, port `5173`) + - (B) **Backoffice** = `@edr/freight-backoffice` (EDR employees, port `5183`) + - (green) **API** = `@edr/freight-api` (NestJS, port `3001`) + - (red) **Payment** = `@edr/payment-api` (NestJS microservice, port `3003`) + +--- + +## 1. System architecture & apps + +| Layer | Package | Port | Base URL / notes | +| ----- | ------- | ---- | ---------------- | +| Customer Portal | `@edr/freight-portal` | 5173 | axios `utils/api.ts`, baseURL `VITE_BASE_API_URL`, React Query | +| Backoffice | `@edr/freight-backoffice` | 5183 | axios `auth/http.ts`, baseURL `${VITE_BASE_API_URL}/api`, React Query | +| Freight API | `@edr/freight-api` | 3001 | NestJS, global prefix `/api`, Postgres schema `freight` | +| Payment API | `@edr/payment-api` | 3003 | NestJS, separate schema `edr_payment`, providers in `@edr/payment-providers` | +| Datastores | — | 5433 | Postgres `edr_freight`; MinIO (files); RabbitMQ (SMS/email/payment events) | + +```mermaid +flowchart LR + subgraph FE["Frontends (React + Vite + React Query)"] + P["(P) Customer Portal :5173"] + B["(B) Backoffice :5183"] + end + + subgraph EDGE["Freight API edge (NestJS :3001)"] + direction TB + CORS["CORS (reflect origin,
credentials, IAM headers)"] + JWT["JwtGuard (global APP_GUARD)
+ HasActiveDelegationGuard"] + PERM["FreightPermissionGuard
(per-route perms)"] + VP["ValidationPipe
(implicitConversion OFF)"] + RTI["ResponseTransformInterceptor
→ { success, data }"] + HEF["HttpExceptionFilter"] + end + + subgraph DOM["Domain modules (~45)"] + direction TB + D1["Identity / Companies / Auth"] + D2["Bookings + Contracts"] + D3["Rule Engine"] + D4["Train Scheduling"] + D5["Warehouse"] + D6["Field Ops (mile/import)"] + D7["Billing"] + D8["Notifications / Inbox"] + end + + subgraph INFRA["Backing services"] + PG[("Postgres
schema: freight")] + MINIO[("MinIO
object store")] + MQ{{"RabbitMQ"}} + PAY["(red) Payment API :3003
schema: edr_payment"] + end + + P -->|"Bearer token (cookie)
axios interceptor"| CORS + B -->|"Bearer token (cookie)
axios interceptor"| CORS + CORS --> JWT --> PERM --> VP --> DOM + DOM --> RTI + DOM --> PG + DOM --> MINIO + DOM -->|"send-sms / send-email"| MQ + DOM -->|"POST /payments/initiate
x-service-token"| PAY + PAY -->|"payment.succeeded webhook
→ /api/internal/payments/mark-paid"| DOM + PAY -.->|"or RabbitMQ payment events"| MQ --> DOM + D8 -->|"socket.io push"| FE +``` + +--- + +## 2. The request pipeline (every FE call) + +Both frontends wrap each API method in an `endpoint(service, action, fn)` helper feeding React Query. +The axios client attaches the JWT and transparently refreshes on `401`. + +```mermaid +sequenceDiagram + autonumber + participant C as React component / hook + participant Q as React Query + participant AX as axios client (interceptors) + participant API as Freight API (:3001) + participant DB as Postgres + + C->>Q: useQuery / useMutation(endpoint) + Q->>AX: call(input) + AX->>AX: request interceptor →
Authorization: Bearer [auth-token cookie] + AX->>API: HTTP /api// + API->>API: CORS → JwtGuard → PermissionGuard → ValidationPipe + alt token valid & permitted + API->>DB: repository query (schema freight) + DB-->>API: rows + API->>API: ResponseTransformInterceptor → { success:true, data } + API-->>AX: 200 { success, data } + AX->>AX: backoffice interceptor unwraps .data
(portal returns raw envelope; callers read .data) + AX-->>Q: payload + Q-->>C: data (+ cache by queryKey) + else 401 Unauthorized + API-->>AX: 401 + AX->>API: POST /api/auth/refresh-token { refreshToken cookie } + alt refresh ok + API-->>AX: { token, refreshToken } + AX->>AX: set cookies, retry original request (_retry) + AX-->>Q: payload + else refresh fails + AX->>AX: clear cookies →
portal: reject · backoffice: redirect /auth + end + else 4xx/5xx + API->>API: HttpExceptionFilter → { success:false, message } + API-->>AX: error + AX-->>Q: throw → onError toast + end +``` + +**Auth model (important):** `SharedAuthModule` (`@tria-plc/api-common`) registers `JwtGuard` + +`HasActiveDelegationGuard` as **global `APP_GUARD`s** — *every* route is JWT-protected unless it +carries `@Public()`. Fine-grained `FreightPermissionGuard([perm])` decorators add permission checks +on staff routes. Explicitly **public** endpoints: `GET /api/files/:fileId`, `POST /api/otp/{send,verify}`, +`GET /api/auth/check-availability`, the `fayda/verification/*` + `/callback` endpoints, +`GET /api/payments/{checkout,receipt/:orderId}`, and the service-to-service `POST /api/internal/payments/mark-paid`. +Real login / JWT issuance lives in the **external IAM package**, not this repo. (Note: `@edr/api-common`'s +`@Public` and `@tria-plc/api-common`'s `@IsPublic` both set the same `"isPublic"` metadata key the guard reads.) + +--- + +## 3. MASTER FLOW — the freight journey (business altitude) + +This is the spine. A shipment travels **customer intake → pricing → approval → contract → customs +clearance → operation request → payment → scheduling/allocation → first-mile → warehouse → train → +arrival → warehouse → last-mile → delivery → tracking**, branching on _container vs bulk_, +_import vs export_, _commercial vs government_, and _one-time vs contract_. + +```mermaid +flowchart TD + start(["Customer signs up
(IAM + Fayda + company onboarding)"]) --> mode{"Booking origin?"} + + mode -->|"One-time shipment"| draft["Create BOOKING (DRAFT) (P)"] + mode -->|"Framework agreement"| cdraft["Create CONTRACT (DRAFT) (P)"] + + %% Contract branch + cdraft --> cprice["Generate price → Submit → Approvals → Sign"] + cprice --> cactive{"Contract type / customs?"} + cactive -->|"Path A: transport-only,
self-clearance"| bookA["Customer books directly
POST /contracts/:id/bookings (P)"] + cactive -->|"Path B: GENERAL + customs"| breq["Customer submits BookingRequest (P)
→ GL accepts → GL creates booking (B)"] + bookA --> draft2["Booking created under contract"] + breq --> draft2 + + %% Booking spine + draft --> price["Generate price (P)
(rule-engine: rates + surcharges)"] + draft2 --> price + price --> submit["Submit → SUBMITTED (P)"] + submit --> intake["Staff accept → PENDING_APPROVAL (B)
(instantiate approval steps)"] + intake --> appr["Approval chain:
LINE_STAFF → DIRECTOR → CEO (B)"] + appr --> gen["Generate contract → CONTRACT_READY (B)"] + gen --> sign["Customer signs (P) → Staff counter-signs (B)"] + sign --> customs{"customsClearingEnabled?"} + + customs -->|"No"| ready["FULLY_EXECUTED"] + customs -->|"Yes"| clr["AWAITING_DOCUMENTS →
customer uploads docs (P) →
GL review/finalize (B) → CLEARANCE_READY"] + clr --> opreq["Customer requests operation (P)
(binding schedule date)"] + ready --> opreq + opreq --> oprev{"Operations review (B)"} + oprev -->|"Request changes"| clr + oprev -->|"Accept: train"| inv["Invoice generated →
enters day batch pool"] + oprev -->|"Accept: road/truck"| road["ROAD_DISPATCH_PENDING
(billed by KM)"] + + inv --> pay["Customer pays invoice (P)
→ (red) gateway → PAID"] + road --> pay + pay --> gov{"Government?"} + gov -->|"Yes"| expedite["governmentExpedite → PAID/Eligible (B)"] + gov -->|"No"| eligible["schedulingStatus = Eligible"] + expedite --> sched + eligible --> sched + + subgraph JOURNEY["Physical movement"] + direction TB + sched["Train schedule: DRAFT → assign bookings →
allocate wagons → finalize → SCHEDULED (B)"] + fm{"EXPORT + first-mile?"} + fmleg["First-mile leg: truck pickup →
RECEIVED_TO_PORT (B)"] + wh_in["Warehouse receive → inspect →
STORED → READY_FOR_LOADING → LOADED (B)"] + disp["Dispatch train → DISPATCHED
(locos ASSIGNED, unpaid EXPIRED) (B)"] + track["Checkpoints logged →
tracking events (customer sees) (P)"] + arrive["Arrive → ARRIVED
(bookings IN_TRANSIT, wagons freed) (B)"] + wh_out["Destination warehouse:
unload → inspect → READY_FOR_PICKUP (B)"] + lm{"IMPORT + last-mile?"} + lmleg["Last-mile leg: truck delivery →
DELIVERED (B)"] + imp["Import customs finalization
(declaration/duty/risk/release) (B)"] + end + + sched --> fm + fm -->|"Yes"| fmleg --> wh_in + fm -->|"No"| wh_in + wh_in --> disp --> track --> arrive --> wh_out + wh_out --> imp + imp --> lm + lm -->|"Yes"| lmleg --> deliver + lm -->|"No"| deliver + + deliver["Release order + gate clearance
(warehouse fees must be PAID) (B)"] + deliver --> pod["Customer approves delivery /
POD captured → DELIVERED (P)"] + pod --> complete(["Booking COMPLETED"]) + + track -.->|"public timeline"| custview["Customer tracking page (P)"] +``` + +**Cross-cutting truth:** almost every hop between domains is fired by a **domain event** (`@OnEvent`), +not a direct call. See §13 for the event web (e.g. `booking.invoice.paid` → advance booking → auto-create +first-mile; `warehouse inspection PASSED` → auto-create last-mile; payment webhook → settle invoice). + +--- + +## 4. Domain map (where each module lives in the journey) + +```mermaid +flowchart LR + subgraph INTAKE["Intake & Identity"] + auth[auth / otp / verifayda] + comp[companies] + sig[signatures] + end + subgraph COMMERCIAL["Commercial"] + bk[bookings] + ct[contracts] + re[rule-engine] + end + subgraph OPS["Rail Operations"] + ts[train-scheduling] + resch[scheduling-reschedule] + fleet[trains/wagons/locomotives/wagon-types] + track[tracking] + end + subgraph GROUND["Ground Operations"] + fmlm[first-mile / last-mile] + imp[import-operations / interchange-documents] + dv[drivers / vehicles] + end + subgraph WH["Warehouse"] + wh[warehouses + inventory + loadings + inspection + rules] + whinv[warehouse-fee-invoices] + end + subgraph MONEY["Money"] + bill[billing] + paymod[payment] + payapi[edr-payment-api] + end + subgraph PLATFORM["Platform / Config"] + dd[dropdown-settings] + fus[file-upload-settings] + files[files / minio] + fac[facilities / routes] + notif[notifications / inbox] + ov[overview] + bo[backoffice/IAM] + end + + INTAKE --> COMMERCIAL --> OPS --> GROUND --> WH --> MONEY + re -.->|rates/approval/priority| COMMERCIAL + COMMERCIAL -.->|invoices| MONEY + WH -.->|storage invoices| MONEY + GROUND -.->|mile invoices| MONEY + PLATFORM -.-> COMMERCIAL +``` + +--- + +## 5. Identity, Access & Onboarding + +### 5.1 Flow + +```mermaid +flowchart TD + su["Signup (external IAM)"] --> chk["GET /auth/check-availability (P)
(email/phone taken?) @Public"] + chk --> otp["POST /otp/send + /otp/verify (P) @Public"] + otp --> fayda{"Identity proofing?"} + fayda -->|"VeriFayda 2.0"| fstart["POST /fayda/verification/start
→ eSignet authorize URL"] + fstart --> fcb["Fayda redirect → GET /callback (ack)
→ GET /fayda/verification/complete
(PKCE code exchange → upsert iam.users)"] + fcb --> onb + fayda -->|"skip"| onb + + onb["POST /companies/onboarding/start (P)
(draft company, placeholder TIN, PENDING)"] + onb --> wiz["Wizard saves incrementally (P):
PATCH /profile · /onboarding-step ·
upload license & docs"] + wiz --> reqs["GET /companies/onboarding/requirements
(server-driven checklist)"] + reqs --> comp["POST /companies/onboarding/complete
→ profiles + company = PENDING"] + comp --> review["Backoffice approves (B):
PATCH /companies/company-profiles/:id/status
→ mint reference, company → ACTIVE"] + review --> book(["Can now book
(assertCompanyProfileApprovedForBooking)"]) +``` + +Company status: `PENDING → ACTIVE` (+ `SUSPENDED`, `BLACKLISTED`). Nationality (`ethiopian`/`foreign`) +drives the required document set. Booking guards elsewhere `403` if the acting profile is not `ACTIVE`. + +### 5.2 Endpoints + +| Method | Path | Action | Guard | FE | +| --- | --- | --- | --- | --- | +| GET | `/api/auth/check-availability` | email/phone dedupe | `@Public` | (P) auth.service | +| GET | `/api/me` | enriched profile + `permissionKeys` + catalog | JwtGuard | (B) auth/api | +| POST | `/api/otp/send` · `/api/otp/verify` | send / verify 6-digit code | `@Public` | (P) auth.service | +| POST | `/api/fayda/verification/start` | start eSignet session (PKCE) | `@Public` + OptionalJwt | (B) verifayda.service | +| GET | `/api/fayda/verification/complete` | code→identity, upsert `iam.users` | `@Public` | (B) verifayda.service | +| GET | `/api/fayda/verification/status` | current user's Fayda link | JwtGuard | — | +| GET | `/callback` | passive Fayda redirect ack (no `/api`) | `@Public` | popup postMessage | +| GET·PUT | `/api/me/signature` | reusable signature (MinIO, base64) | JwtGuard | (P)(B) signatures.service | +| GET | `/api/test_user1` · `/api/test_user2` | permission-guard demo | `PermissionGuard` | (B) demo pages | +| GET | `/api/companies/getInfo` · `/profile` · `/dashboard` | company info / KPIs | JwtGuard | (P) companies.service | +| POST | `/api/companies/fetch-etrade-info` | pull reg data by TIN | JwtGuard | (P) | +| PATCH | `/api/companies/profile` | update profile (JSONB attrs) | JwtGuard | (P) | +| POST | `/api/companies/onboarding/start` · `/complete` | onboarding lifecycle | JwtGuard | (P) | +| PATCH | `/api/companies/onboarding-step` · `/active-mode` | wizard state / mode switch | JwtGuard | (P) | +| GET | `/api/companies/onboarding/requirements` | server checklist | JwtGuard | (P) | +| POST·GET | `/api/companies/company-profiles/:id/license` | license file up/list | JwtGuard | (P) | +| POST | `/api/companies/company-profiles` · `/company-profile` | add operational profile(s) | JwtGuard | (P) | +| POST·GET·PATCH·DELETE | `/api/companies` (+`/:id`) | company CRUD | `@FreightAdmin` writes | (B) customers.service | +| GET | `/api/companies/stats` | KPI strip | JwtGuard | (B) | +| PATCH | `/api/companies/company-profiles/:id/status` | approve profile → mint ref | `@FreightAdmin` | (B) | +| GET·POST | `/api/companies/:companyId/documents` | company docs (signed URLs) | JwtGuard | (P)(B) | +| GET | `/api/notifications` (+`/unread-count`) | inbox list / unread | JwtGuard | (P)(B) notificationsApi | +| PATCH·POST | `/api/notifications/:id/read` · `/read-all` | mark read (WS re-emit) | JwtGuard | (P)(B) | +| WS | `NOTIFICATION_WS_NAMESPACE` | live push (server→client) | WsAuth handshake | (P)(B) useNotificationSocket | + +`notifications` module = SMS/email transport over RabbitMQ (no HTTP routes). Inbox fan-out writes one +`notifications` row + WS push per recipient; **HIGH** priority also emails + SMSs (best-effort). + +--- + +## 6. Bookings — the core state machine + +```mermaid +stateDiagram-v2 + [*] --> DRAFT: create (P) (staff commercial auto price+submit) + DRAFT --> SUBMITTED: submit (P) + DRAFT --> PRICE_CHANGED_PENDING_CONFIRM: price moved + PRICE_CHANGED_PENDING_CONFIRM --> SUBMITTED: confirm-submit (P) + SUBMITTED --> REJECTED: customer reject (price) (P) + SUBMITTED --> CHANGES_REQUESTED: staff request-changes (B) + CHANGES_REQUESTED --> SUBMITTED: edit + resubmit (P) + SUBMITTED --> PENDING_APPROVAL: staff/accept (B) (instantiate approval steps) + SUBMITTED --> REJECTED: staff/reject (B) + PENDING_APPROVAL --> APPROVED_PENDING_SIGNATURE: line-staff approve (B) + APPROVED_PENDING_SIGNATURE --> APPROVED: director + ceo approve (B) + PENDING_APPROVAL --> REJECTED: rejectStep (B) + APPROVED --> CONTRACT_READY: contract/generate (B) + CONTRACT_READY --> SIGNED_CUSTOMER: customer sign (P) + SIGNED_CUSTOMER --> AWAITING_DOCUMENTS: counter-sign, IMPORT/EXPORT (B) + SIGNED_CUSTOMER --> FULLY_EXECUTED: counter-sign, DOMESTIC (B) + AWAITING_DOCUMENTS --> DOCUMENTS_UNDER_REVIEW: clearance/documents (P) + DOCUMENTS_UNDER_REVIEW --> CLEARANCE_READY: review + finalize (B) + CLEARANCE_READY --> OPERATION_REQUEST_PENDING: clearance/proceed (P) + OPERATION_REQUEST_PENDING --> OPERATION_CHANGES_REQUESTED: review=REQUEST_CHANGES (B) + OPERATION_CHANGES_REQUESTED --> OPERATION_REQUEST_PENDING: re-proceed (P) + OPERATION_REQUEST_PENDING --> ROAD_DISPATCH_PENDING: accept=road (B) (invoice, KM billed) + OPERATION_REQUEST_PENDING --> FULLY_EXECUTED: accept=train (B) (invoice) + FULLY_EXECUTED --> SELECTED_FOR_BATCH: batch engine offers wagons (sys) + SELECTED_FOR_BATCH --> PAID: pay invoice (P) + ROAD_DISPATCH_PENDING --> PAID: pay invoice (P) + PAID --> IN_TRANSIT: operations/start-transit (B) + IN_TRANSIT --> COMPLETED: operations/complete (B) + DRAFT --> PENDING_CONSOLIDATION: requestConsolidation (usually set on submit) + DRAFT --> CANCELLED: cancel (B) + PENDING_APPROVAL --> CANCELLED: cancel (B) + OPERATION_REQUEST_PENDING --> CANCELLED: cancel (B) + note right of PAID + governmentExpedite (B) jumps + gov bookings straight to PAID/Eligible + end note + note left of CANCELLED + cancel is staff-only and allowed ONLY from + DRAFT, SUBMITTED, PRICE_CHANGED_PENDING_CONFIRM, + CHANGES_REQUESTED, PENDING_APPROVAL, + CONTRACT_READY, OPERATION_REQUEST_PENDING + end note + REJECTED --> [*] + CANCELLED --> [*] + COMPLETED --> [*] +``` + +> **Accuracy notes (verified against code):** +> - Counter-sign branch is keyed on **trade direction**, not a customs flag: `IMPORT`/`EXPORT` → +> `AWAITING_DOCUMENTS` (even when customs is off — a lighter "without customs" clearance doc-set still +> applies); only `DOMESTIC` → `FULLY_EXECUTED`. +> - **Domestic** bookings skip the operation-request/clearance phase entirely — counter-sign enqueues +> them straight into the scheduling batch pipeline (`enqueueScheduleProcessing`). +> - Train `operation/review` accept sets **`FULLY_EXECUTED`** (day batch holding pool). `SELECTED_FOR_BATCH` +> is set **later** by the batch engine when a wagon offer/reservation is made — not at accept. +> - `APPROVED_PENDING_SIGNATURE` is a real intermediate (line-staff approves first, then director+CEO). +> - Full `BOOKING_STATUSES` has 35 values; this diagram is the live commercial subset (legacy statuses +> like `WAGON_ASSIGNED`, `INVOICED`, `PNR_GENERATED` are unused). + +Key endpoints (customer (P) / staff (B), `bk:` = `bookings:` perms): + +| Method | Path | Action | Guard | +| --- | --- | --- | --- | +| POST | `/api/bookings` | create | in-body (gov→`bk:staff_accept`) | +| PATCH·DELETE | `/api/bookings/:id` | update / soft-delete DRAFT | company-scoped | +| POST | `/api/bookings/:id/generate-price` | price preview (rule-engine) | company-scoped | +| POST | `/api/bookings/:id/submit` · `/confirm-submit` | submit (rate snapshot) | company-scoped | +| POST | `/api/bookings/:id/reject` | customer rejects price | company-scoped | +| POST | `/api/bookings/:id/staff/accept` | → PENDING_APPROVAL | `bk:staff_accept` | +| POST | `/api/bookings/:id/staff/request-changes` · `/staff/reject` | intake outcomes | `bk:request_changes` / `bk:reject` | +| POST | `/api/bookings/:id/approval-steps/:stepId/approve` · `/reject` | approval chain | role perms | +| POST | `/api/bookings/:id/contract/generate` | → CONTRACT_READY | `bk:generate_contract` | +| POST | `/api/bookings/:id/contract/sign` · `/marketing/approve` | sign / counter-sign | in-body / `bk:sign_staff` | +| GET | `/api/bookings/:id/contract/{view,document}` | HTML / PDF | company-scoped | +| GET·POST | `/api/bookings/:id/clearance` (+`/documents`,`/review`,`/finalize`,…) | customs clearance | `bk:*` / `ct:clearance_*` | +| POST | `/api/bookings/:id/clearance/proceed` | request operation | company-scoped | +| POST | `/api/bookings/:id/operation/review` | accept/changes (+invoice) | `bk:operations` | +| POST | `/api/bookings/:id/government-expedite` | gov shortcut → PAID | `bk:staff_accept` | +| POST | `/api/bookings/:id/operations/start-transit` · `/complete` | transit lifecycle | `bk:operations` | +| POST | `/api/bookings/:id/allocate-containers` | assign containers↔vehicles | `allocation:manage` | +| POST·GET·DELETE | `/api/bookings/:id/consolidation` | pair/unpair wagon-share | company-scoped | +| POST | `/api/bookings/:id/customer-truck-assignment` | external truck for pickup | company-scoped | +| GET | `/api/bookings/:id/tracking` | consignment + tracking events | company-scoped | +| GET | `/api/bookings` · `/list-summary` · `/queues/:queue` | lists (branch by perm) | `bk:view` / `bk:clearance_view` | + +--- + +## 7. Contracts — framework agreements & booking paths + +```mermaid +stateDiagram-v2 + [*] --> DRAFT: create (P) + DRAFT --> SUBMITTED: submit (P) (freeze rate snapshots) + SUBMITTED --> PENDING_APPROVAL: staff/accept (B) + SUBMITTED --> CHANGES_REQUESTED: request-changes (B) + CHANGES_REQUESTED --> SUBMITTED: resubmit (P) + SUBMITTED --> REJECTED: reject (B) + PENDING_APPROVAL --> APPROVED: approve chain (B) + APPROVED --> CONTRACT_READY: contract/generate (B) + CONTRACT_READY --> SIGNED_CUSTOMER: customer sign (P) + SIGNED_CUSTOMER --> AWAITING_CLEARANCE_DOCUMENTS: counter-sign, IMPORT/EXPORT (not GENERAL+customs) (B) + SIGNED_CUSTOMER --> CONTRACT_ACTIVE: counter-sign, GENERAL+customs or DOMESTIC (B) + SIGNED_CUSTOMER --> FULLY_EXECUTED: counter-sign, ONE_TIME DOMESTIC (B) + CONTRACT_ACTIVE --> [*]: renew → RENEWAL_DRAFT +``` + +> Diagram shows the live path; `CONTRACT_STATUSES` has **24 values** total (adds APPROVED_PENDING_SIGNATURE, +> CLEARANCE_UNDER_REVIEW, CLEARANCE_READY_FOR_BOOKING, ACTIVE_SHIPMENT_IN_PROGRESS, CONTRACT_CLOSED, CANCELLED, +> RENEWAL_SUBMITTED/PENDING_APPROVAL, AMENDMENTS_PROPOSED, ARCHIVED — see §15). **GENERAL+customs skips the +> contract clearance cycle → `CONTRACT_ACTIVE` directly** (clearance runs per-booking, Path B); only IMPORT/EXPORT +> one-time or self-clearance opens the contract-level `AWAITING_CLEARANCE_DOCUMENTS` cycle. + +**Two ways a contract spawns shipment bookings:** + +```mermaid +flowchart TD + active["Contract ACTIVE / SELF_CLEARED"] --> path{"Contract path"} + path -->|"Path A: transport-only"| a1["Ops reviews self-clearance docs (B)
(ops-review → ops-finalize → SELF_CLEARED)"] + a1 --> a2["Customer books directly (P)
POST /contracts/:id/bookings"] + path -->|"Path B: GENERAL + customs"| b1["Customer submits BookingRequest (P)
POST /contracts/:id/booking-requests"] + b1 --> b2["GL queue → accept (B)
(ct:create_booking) → GL creates booking"] + a2 --> cap["createUnderContract:
window + capacity draw-down check"] + b2 --> cap + cap --> spawn(["New Booking under contract
(bookings.contract_id)"]) +``` + +Contract clearance is **phased** (ET vs DJ permissioned): declaration → duty advice → duty slip → +transit permit → delivery/release order → T1 docs/close → final invoice → incidents. `clearanceStatus` +is a separate axis (`AWAITING_DOCUMENTS → DOCUMENTS_UNDER_REVIEW → CLEARANCE_READY_FOR_BOOKING / +SELF_CLEARED / ACTIVE_SHIPMENT_IN_PROGRESS`). ~60 contract routes total. Per-booking clearance +actions (`duty`, `risk`, `t1-documents`, `t1-close`, `final-invoice`, `second-duty`, `transport-document`, +`station-assign`, `incidents`) hang off `/api/contracts/bookings/:bookingId/*`; note **`declaration` is a +contract-level route** (`/api/contracts/:id/clearance/declaration`), not a booking-scoped one. + +### Consignment / Cargo / Container (fleet-side records) + +| Entity | Controller | Guard | Lifecycle | Callers | +| --- | --- | --- | --- | --- | +| Consignment | `/api/consignments` (create/list/get) | `FleetView`/`Manage` | `Pending → …` (downstream shipment record; booking `:id/tracking` reads it) | (P) read-only | +| Cargo | `/api/cargoes` (+ `/load` `/unload` `/deliver`) | `FleetView`/`Manage` | `PENDING → LOADED → UNLOADED / DELIVERED` (POD) | (B) cargoService | +| Container | `/api/containers` (+ `/assign-wagon` `/unassign-wagon`) | `FleetView`/`Manage` | `AVAILABLE → LOADED → IN_TRANSIT …` | (B) containerService | + +--- + +## 8. Rule Engine — the pricing & approval brain + +`RuleEngineService.evaluate(input)` is injected into bookings & contracts pricing. One pass pulls all +rule tables and returns `{ priorityScore, appliedModifiers, containerWeightResults, warnings, +hardBlocked, requiresDirectorApproval }`. + +```mermaid +flowchart TD + ev["evaluate(BookingEvaluationInput)"] --> rates["rates.findLiveRates()
(only LIVE)"] + rates --> sur{"surcharge triggers"} + sur -->|"HAZARDOUS/REEFER/OVERWEIGHT/
SHIPPING_LINE/CONSOLIDATION"| mods["appliedModifiers →
surcharge line-items"] + mods --> snap["snapshotRates → booking_rate_snapshots
(freeze exact rate used)"] + ev --> wlr["weight-limit-rules"] + wlr --> block{"VGM > maxCapacityTons?"} + block -->|Yes| hard["HARD BLOCK (400)"] + block -->|"over maxVgm, within cap"| warn["warning + OVERWEIGHT surcharge"] + ev --> appr["approval-rules →
instantiateApprovalSteps
(requiredRole/blocksRole/stepOrder)"] + ev --> prio["priority-configs + serviceType bonus +
GOVERNMENT_PRIORITY_BONUS → priorityScore"] + prio --> schedorder["train-scheduling orders by priorityScore"] +``` + +**Rate lifecycle:** `DRAFT → (submit) PENDING_APPROVAL → (CEO approve) LIVE`. Only LIVE rates apply. + +| Resource | Base path | Guard | Notes | +| --- | --- | --- | --- | +| approval-rules | `/api/approval-rules` (+`/chain`,`/reorder`,`/:id/move-order`) | `ruleEngine.view/manage(approval-rules)` | ordered chain | +| cargo-types | `/api/cargo-types` | `…(cargo-types)` | portal reads via `bookings/reference-data` | +| container-types | `/api/container-types` | `…(container-types)` | portal indirect | +| priority-configs | `/api/priority-configs` | `…(priority-configs)` | WAGON / CURRENCY bands | +| rates | `/api/rates` (+`/live`,`/:id/submit`,`/approve`) | `…(rates)` | DRAFT→PENDING→LIVE | +| service-types | `/api/service-types` | `…(service-types)` | `includesFirstMile/LastMile` flags | +| shipping-lines | `/api/shipping-lines` | `…(shipping-lines)` | surcharge trigger | +| weight-limit-rules | `/api/weight-limit-rules` | `…(weight-limit-rules)` | VGM hard-block | +| yards | `/api/yards` | `…(yards)` | routes/warehouses read | + +**Settings & files** (reads open, writes `@FreightAdmin`): +`/api/dropdown-settings/*`, `/api/file-upload-settings/*` (config that drives portal forms; +server enforces *required-doc presence* at clearance, not size/MIME — those are client-side). +`GET /api/files/:fileId` is `@Public` (browsers load `/` without a bearer); upload is **direct +multipart** (multer memory → `FilesService` → MinIO `putObject`), presigned URLs used only for authenticated +reads (300 s TTL). `routes` (`route_milestones`) and `facilities` are config readers with **no permission +decorator** (behind the global JwtGuard only). NOTE: Note `FacilitiesModule` is never imported into `AppModule`, +so `/api/facilities` is unmounted/dead. + +--- + +## 9. Train Scheduling & Rail Operations + +Two consist models: **`trains`** = static fleet inventory (never created by scheduling); +**`train_sets`** = the operational consist scheduling builds per departure (**≥2 locomotives** + +wagon-type slots, physical wagons *pinned* later). + +```mermaid +stateDiagram-v2 + [*] --> DRAFT: create schedule (B) (≥2 locos, derive direction, freeze window rule) + DRAFT --> DRAFT: assign-bookings / run-allocation / pin-wagons (B) + DRAFT --> SCHEDULED: finalize (B) (bookings → Scheduled, ≥1 booking) + SCHEDULED --> DISPATCHED: dispatch (B) (train_number, locos ASSIGNED, window CLOSED, unpaid EXPIRED) + DISPATCHED --> DISPATCHED: recordCheckpoint (B) (corridor stations) + DISPATCHED --> ARRIVED: arrive (B) (bookings IN_TRANSIT, locos+wagons freed, warehouse arrival automation) + DRAFT --> CANCELLED: cancel (B) + SCHEDULED --> CANCELLED: cancel (B) + ARRIVED --> [*] +``` + +**Reschedule** (`DRAFT`/`SCHEDULED` only): `preview` merges current + incoming bookings, sorts by +`compareSchedulingPriority` (**government first, then priorityScore**), greedily keeps those that still +fit → *retained*; overflow → *displaced*; commercial displaced are *readmitted* if room remains. +`execute` re-verifies, optionally sets new departure, unassigns displaced, re-assigns final, writes a +`scheduling_events` audit row. Triggers: `GOVERNMENT_PREEMPT`, `TRAIN_MAINTENANCE`. + +Endpoint groups (`train-scheduling` prefix, `trainScheduling.view/manage`): + +| Group | Representative routes | +| --- | --- | +| Discovery (customer (P), unguarded) | `bookable-schedules`, `available-days`, `available-days-for-cargo`, `my-booking-windows`, `contracts/:id/booking-windows` | +| Board (staff (B)) | `batch-board`, `batch-board/:id`, `eligible-bookings`, `container|bulk/eligible-bookings`, `global-rules` | +| Build | `container|bulk/preview`, `container|bulk/schedules` (create), `:id/assign-bookings`, `:id/assign-unassigned-booking`, `:id/pin-wagons`, `:id/run-allocation`, `:id/run-batch` | +| Composition edits | `:id/wagons/:wagonId` (remove slot), `:id/container-items/:itemId`, `bookings/:bookingId/{mark-paid,expire,move-schedule}` | +| Lifecycle | `schedules/:id/{finalize,dispatch,arrive,booking-window,doc-review-complete}`, `{container\|bulk}/schedules/:id/cancel` | +| Tracking | `schedules/:id/checkpoints` (GET/POST) → writes `train_checkpoint_events` | +| Djibouti import ops | `:id/import-djibouti/*` (gatepass, ready-for-loading, loaded, depart, load-list) | +| Reschedule | `:id/reschedule/preview`, `:id/reschedule/execute`, `:id/maintenance` | + +**Fleet master data** (`FleetView/Manage`): `/api/trains` (+`/:trainId/reorder-wagons`), `/api/wagons` +(+`/assign-train`,`/unassign-train`), `/api/locomotives` (+`/decommission`), `/api/wagon-types` +(rule-engine guarded). **Asset records** (unguarded, keyed by *road* `vehicleId`): `/api/maintenance/*`, +`/api/fuel/*`. **`fleet_events`** is an append-only audit read via `drivers/:id/history` & +`vehicles/:id/history`. + +**Tracking (customer-facing):** `GET /api/tracking/:consignmentId` → `tracking_events` timeline +(`location`, `ConsignmentStatus`, `occurredAt`), consumed by portal `TrackingPage`. It is **JWT-guarded** +(no permission decorator — not public). Distinct from staff train **checkpoints** (`train_checkpoint_events`, +written by `recordCheckpoint`/`arrive`). NOTE: **`TrackingService.record()` has no caller anywhere in the +codebase — nothing writes `tracking_events`, so the customer tracking timeline is currently unpopulated; +only the staff `train_checkpoint_events` store is written.** + +--- + +## 10. Warehouse — inventory lifecycle + +Hierarchy `Facility → Warehouse → Yard → Zone`; every level tracks weight/volume/container capacity kept +in sync by `applyCapacityDelta`. `warehouse_inventory` carries nullable FKs to `booking`, `cargo`, +`container` — the join point between warehouse and the shipment. + +```mermaid +stateDiagram-v2 + [*] --> RECEIVED: receive / bulkReceive (B) + [*] --> UNLOADED: auto-unload-arrived (import train) (B) + RECEIVED --> STORED: store (B) (allocation rule picks yard/zone) + UNLOADED --> STORED: store (B) + UNLOADED --> READY_FOR_PICKUP: inspection PASSED + IMPORT (B) + RECEIVED --> READY_FOR_PICKUP: inspection PASSED + IMPORT (B) + STORED --> RESERVED: reserve (B) (booking PAID) + RESERVED --> READY_FOR_LOADING: mark-ready-for-loading (B) (inspection PASSED) + READY_FOR_LOADING --> LOADED: load onto wagon (B) (+ warehouse_loadings) + LOADED --> DISPATCHED: dispatch / bulk-dispatch-export (B) + DISPATCHED --> UNLOADED_AT_DJIBOUTI_PORT: auto-unload-at-djibouti (B) + READY_FOR_PICKUP --> DELIVERED: release → deliver (B) (POD, fees PAID via gate-clearance) + READY_FOR_PICKUP --> STORED: re-store import item (B) + READY_FOR_PICKUP --> DISPATCHED: dispatch out (B) + UNLOADED_AT_DJIBOUTI_PORT --> [*] + DELIVERED --> [*] +``` + +**Export branch:** receive → STORED → RESERVED (booking PAID) → READY_FOR_LOADING → LOADED → DISPATCHED +→ UNLOADED_AT_DJIBOUTI_PORT. Note `store()` does **not** check inspection — `RECEIVED → STORED` is legal +without it; inspection **PASSED** is enforced only at `mark-ready-for-loading`. **Import branch:** UNLOADED +→ inspect PASSED → READY_FOR_PICKUP (auto-creates +last-mile if requested) → release → DELIVERED. Every transition writes `warehouse_activity_log`. + +**Storage billing** is *not* a separate table — `WarehouseInvoiceService` is a thin layer over the +central **billing** module (global `Invoice` rows, `source='warehouse'`, `sourceId=inventoryId`). Fees = +`STORAGE_FEE` + `DEMURRAGE` via `warehouse_fee_rules` (free-days grace, tiers, FX-converted). **Unpaid +warehouse fees block exit:** `gateClearance`/`release` call `findBlockingInvoice` / `assertClearanceAllowed`. + +Controller families (84 routes, all called by backoffice `warehouse.service.ts`; **no per-route +permission decorators → behind the global JwtGuard only**): `warehouses` · `warehouse-yards` · +`warehouse-zones` · `warehouse-inventory` (queries + 25 mutation actions incl. bulk + import/export +queues, and the gate release `warehouse-inventory/:id/gate-clearance`) · `warehouse-loadings` · +inspection (`…/inspection-reports`) · fee-invoices (`…/generate-fee-invoice`, `warehouse-fee-invoices/*` +incl. `pay`, `pay-online`) · rules (`warehouse-allocation-rules`, `warehouse-fee-rules`, +`warehouse-allocation/preview`). + +> Portal touches only: `bookings/:id/warehouse-fee-invoices`, invoice `by-id`/`document`/`receipt`/ +> `pay-online`, and `bookings/:bookingId/approve-delivery` (customer signs handover). Everything else (B). + +--- + +## 11. Field Operations — first/last mile & import customs + +```mermaid +flowchart TD + binv["booking.invoice.paid event"] --> advance["advanceBookingOnPayment → booking PAID"] + advance --> fmreq{"EXPORT + first-mile requested?"} + fmreq -->|Yes| fmaccept["firstMileService.acceptBooking
(auto-create leg)"] + fmreq -->|No| skip1["—"] + fmaccept --> fmleg + + subgraph FM["First-mile (EXPORT origin road leg)"] + fmleg["READY_TO_TRANSIT"] --> fmveh["setVehicles → vehicle BUSY,
SMS driver, fleet_events"] + fmveh --> fmtransit["IN_TRANSIT (needs assigned vehicle)"] + fmtransit --> fmdone["RECEIVED_TO_PORT (free vehicles)"] + fmleg --> fminv["generate-invoice → FIRST_MILE fee
(locks distances once invoiced)"] + end + + whrcv["warehouse inspection PASSED (IMPORT only)"] --> lmaccept["lastMileService.acceptBooking(reference)"] + lmaccept --> lmleg + subgraph LM["Last-mile (IMPORT destination road leg)"] + lmleg["READY_TO_TRANSIT"] --> lmtransit["IN_TRANSIT"] --> lmdone["DELIVERED (free vehicles)"] + lmleg --> lminv["generate-invoice → LAST_MILE fee"] + end + + subgraph IMP["Import customs finalization (per booking, timestamp-driven)"] + direction TB + up["upload docs (IM4/IM5/T1_CLOSURE/…)"] --> decl["record declaration serial"] + decl --> notify["notify duties/taxes"] + notify --> paid["mark duties paid (needs CUSTOMER_PAYMENT_SLIP)"] + paid --> risk["assign risk (GREEN/YELLOW/BLUE/RED)"] + risk --> rel["release-permitted (asserts T1 + release permit + declaration + risk + paid)"] + end +``` + +| Module | Base | Guard | Terminal state | +| --- | --- | --- | --- | +| first-mile | `/api/first-mile` (+`/accept/:ref`,`/:id/{vehicles,distances,invoice}`) | `trainScheduling.view/manage` | `RECEIVED_TO_PORT` | +| last-mile | `/api/last-mile` (same shape) | `trainScheduling.view/manage` | `DELIVERED` | +| import-operations | `/api/import-operations/{customs,djibouti-incidents,empty-container-returns}/*` | none (global JwtGuard) | `completedAt` | +| interchange-documents | `/api/interchange-documents` (+`/generate-from-schedule`,`/:id/{acknowledge,dispute,cancel}`) | none | `ACKNOWLEDGED / DISPUTED` | +| drivers | `/api/drivers` (+`/:id/history`) | `FleetView/Manage` | soft-delete | +| vehicles | `/api/vehicles` (+`/:id/history`) | `FleetView/Manage` | soft-delete | + +Interchange documents are the **rail↔port handover manifest** — generated from a train schedule, +snapshotting booking/container/cargo lines with per-item `conditionStatus` derived from warehouse +inspection flags. Status `DRAFT → GENERATED → ACKNOWLEDGED | DISPUTED | CANCELLED`. All FE callers (B). + +**Mile trigger precision (verified):** first-mile is created only on `booking.invoice.paid` → +`advanceBookingOnPayment` → `firstMile.acceptBooking(bookingId)` when `EXPORT` + first-mile requested. +Last-mile is created **only on IMPORT inspection PASSED** (two call sites: `warehouse-inspection.service` +and the bulk-inspect branch of `warehouse-inventory.service`) — **not** on warehouse *receive*. The IMPORT +constraint is enforced by the warehouse caller, not inside `lastMile.acceptBooking(reference)`. Auto-created +legs enter at **`READY_TO_TRANSIT`** (the `PAYMENT_PENDING` entity default is bypassed). + +--- + +## 12. Billing & Payment + +### 12.1 Invoice lifecycle + +Invoices are **source-agnostic** — `BillingService.generateInvoice()` is the single factory called by +domain services (never a controller): `source ∈ {booking, warehouse, first_mile, last_mile}` (the enum +also defines an unused `demurrage`), numbered `INV-YYYYMMDD-#####`, `dueAt = now + 14d`. **Initial status +varies by source:** booking invoices start `DRAFT` (issued at operation-accept via `billing.updateStatus`); +the `generateInvoice` default is `PENDING`; warehouse + contract-GL invoices start `ISSUED`. + +```mermaid +stateDiagram-v2 + [*] --> DRAFT: booking invoice (issued at operation-accept) + [*] --> PENDING: generateInvoice default + [*] --> ISSUED: warehouse / contract-GL invoice + DRAFT --> ISSUED: billing.updateStatus + PENDING --> PARTIALLY_PAID: recordPayment (partial, offline) + ISSUED --> PARTIALLY_PAID: recordPayment (partial, offline) + PENDING --> PAID: markInvoiceAsPaid (gateway, full) + ISSUED --> PAID: markInvoiceAsPaid (gateway, full) + PARTIALLY_PAID --> PAID: final payment + PENDING --> EXPIRED: expirePayable (pay window lapses) + ISSUED --> CANCELLED: cancelInvoice (no payments) + PAID --> REFUNDED: markInvoiceAsRefunded (paidAmount>0) + PAID --> [*] + note right of PAID + emits ${source}.invoice.paid + (sources use first_mile / last_mile, underscores) + → domain listeners advance booking / mile / warehouse + end note + note left of ISSUED + OVERDUE exists in the enum but NO code sets it + (no cron / setter) — effectively unused + end note +``` + +`OPEN_STATUSES = {Issued, Pending, PartiallyPaid, Overdue}` are payable. Transitions lock the row +(`pessimistic_write`); the event fires **after commit** for self-managed transitions, but **inline before +commit** when the transition is enlisted in a caller-supplied transaction `manager`. + +### 12.2 freight-api ↔ payment-api integration + +```mermaid +sequenceDiagram + autonumber + participant U as Customer (P) + participant FB as Freight billing (:3001) + participant PA as Payment API (red) (:3003) + participant PV as Provider (Telebirr/Waafi/…) + participant OB as Payment outbox + participant FI as Freight internal ctrl + + U->>FB: POST /billing/my-invoices/:id/pay + FB->>FB: payInvoice → validate OPEN, balance>0 + FB->>PA: POST /payments/initiate (x-service-token)
service=FREIGHT, referenceId=sourceId, amountMinor + PA-->>FB: { intentId, clientAction (REDIRECT/LAUNCH_APP/COLLECT_OTP) } + FB->>FB: store paymentId on invoice (correlation) + FB-->>U: clientAction → redirect to provider + U->>PV: authorize payment + PV->>PA: webhook POST /webhooks/{provider} + PA->>PA: verify signature, dedupe, intent state machine + PA->>OB: write PaymentEvent (payment.succeeded) + OB->>FI: POST /api/internal/payments/mark-paid (@Public, x-service-token) + Note over OB,FI: or RabbitMQ → PaymentEventsConsumer + FI->>FB: handlePaymentEvent → settleByPaymentId → markInvoiceAsPaid + FB->>FB: emit booking.invoice.paid + FB-->>U: invoice PAID (poll / notification) +``` + +> NOTE: **Demo shortcut in `payInvoice`:** today, if the provider doesn't settle synchronously, freight +> self-fires `handlePaymentEvent(payment.succeeded)` inline (marked TODO/remove) — invoices settle at +> pay-time without a real webhook. Providers: **Telebirr / CBE_BIRR / EBIRR** (ET), **Waafi / DMoney** +> (DJ), **CARD** (intl), **CAC_BANK** (OTP). Payment DB is a **separate `edr_payment` schema** — no +> cross-schema FKs; `referenceId` is a soft link. + +### 12.3 Endpoints + +| Method | Path | Facing | Guard | +| --- | --- | --- | --- | +| GET | `/api/billing/invoices` (+`/:id`,`/:id/document`,`/receipt`) | (B) backoffice | `bookings.view` | +| GET | `/api/billing/my-invoices` (+`/:id`,`/document`,`/receipt`) | (P) portal | `@CurrentUser` ownership | +| POST | `/api/billing/my-invoices/:id/pay` | (P) portal | ownership | +| POST | `/api/payments/initiate` | central | JwtGuard (no permission — **not** public) | +| GET | `/api/payments/checkout` | redirect | `@Public` | +| GET | `/api/payments/{summary,all}` | (B) backoffice | `bookings.view` | +| GET | `/api/payments/by-company/:companyId/customer-view` | (B) | none | +| GET | `/api/payments/intents/:bookingId` · `/receipt/:orderId` | reconcile / receipt | none / `@Public` | +| POST | `/api/internal/payments/mark-paid` | (red) service→service | `@Public` (NOTE: currently unauthenticated) | +| POST·GET·PUT | `/api/backoffice/organizations/:orgId/*` | (B) IAM user/role mgmt (NOT billing) | `@FreightAdmin` | + +`GET /api/overview*` (7 tabs, `bookings.view`) is the backoffice dashboard aggregator over 11 repos. + +--- + +## 13. Cross-cutting event web (`@OnEvent`) + +The domains are stitched together by events, not direct calls. This is why the master flow "just happens". + +```mermaid +flowchart LR + pay["Payment webhook / demo shortcut"] --> settle["billing.settleByPaymentId → markInvoiceAsPaid"] + settle --> ev1{{"${source}.invoice.paid"}} + ev1 -->|source=booking| adv["booking-invoice: advanceBookingOnPayment → PAID"] + adv --> fm["firstMile.acceptBooking (EXPORT + requested)"] + adv --> batch["train-scheduling batch: markPaid → allocate"] + ev1 -->|source=first_mile| e2{{"first_mile.invoice.paid"}} --> fmp["NOTE: intended: leg paid=true
(listener typo 'firstmile.invoice.paid' → never fires)"] + ev1 -->|source=last_mile| e3{{"last_mile.invoice.paid"}} --> lmp["last-mile → DELIVERED, paid=true"] + ev1 -->|source=warehouse| e4{{"warehouse.invoice.paid"}} --> whp["settle warehouse fee → unblock gate"] + + arrive["train arrive"] --> whauto["warehouse arrival automation:
auto-unload arrived bookings"] + insp["warehouse inspection PASSED (IMPORT)"] --> lmacc["lastMile.acceptBooking → READY_FOR_PICKUP"] + + assign["mile setVehicles"] --> veh["vehicle BUSY + SMS driver + fleet_events"] + release["mile terminal / delete"] --> free["vehicle FREE (releaseIfUnused)"] + + notify["notification-inbox.notify"] --> ws["WebSocket push (always)"] + notify -->|HIGH priority| smsemail["+ SMS + email via RabbitMQ"] +``` + +--- + +## 14. Portal vs Backoffice — who does what + +| Capability | (P) Portal (customer) | (B) Backoffice (employee) | +| --- | --- | --- | +| Identity / onboarding | signup, OTP, Fayda, company onboarding, profile | company approval, IAM user/role mgmt | +| Bookings | create, price, submit, sign, upload docs, pay, approve delivery, track | accept, approve chain, generate contract, clearance review, operation review, allocate, dispatch | +| Contracts | create, submit, sign, booking-requests, self-clearance slips | approve, generate, phased clearance, GL booking creation | +| Rule engine | reads only via `bookings/reference-data` | full CRUD (rates approval, approval rules, priorities) | +| Scheduling | discover bookable days/schedules | build/finalize/dispatch/arrive/reschedule trains | +| Warehouse | pay storage fees, view invoices, approve handover | full inventory lifecycle + fees + rules | +| Field ops | (none direct) | first/last mile, import customs, interchange docs, fleet | +| Billing | pay own invoices, download docs/receipts | invoice + payment dashboards, per-customer views | +| Notifications | inbox + WS | inbox + WS | + +--- + +## 15. Status / state reference + +| Entity | States (happy path → terminal) | +| --- | --- | +| Company | `PENDING → ACTIVE` (+ SUSPENDED, BLACKLISTED) | +| Booking | `DRAFT → SUBMITTED → PENDING_APPROVAL → APPROVED_PENDING_SIGNATURE → APPROVED → CONTRACT_READY → SIGNED_CUSTOMER → [IMPORT/EXPORT: AWAITING_DOCUMENTS → DOCUMENTS_UNDER_REVIEW → CLEARANCE_READY → OPERATION_REQUEST_PENDING → (train) FULLY_EXECUTED → SELECTED_FOR_BATCH / (road) ROAD_DISPATCH_PENDING] · [DOMESTIC: → FULLY_EXECUTED → SELECTED_FOR_BATCH] → PAID → IN_TRANSIT → COMPLETED` (branches: REJECTED, CANCELLED, CHANGES_REQUESTED, OPERATION_CHANGES_REQUESTED, PENDING_CONSOLIDATION). 35 statuses total; ~10 legacy ones unused. | +| Contract | `DRAFT → SUBMITTED → PENDING_APPROVAL → APPROVED_PENDING_SIGNATURE → APPROVED → CONTRACT_READY → SIGNED_CUSTOMER → AWAITING_CLEARANCE_DOCUMENTS / CONTRACT_ACTIVE / FULLY_EXECUTED` (+ CLEARANCE_UNDER_REVIEW, CLEARANCE_READY_FOR_BOOKING, ACTIVE_SHIPMENT_IN_PROGRESS, CONTRACT_CLOSED, CANCELLED, RENEWAL_DRAFT/SUBMITTED/PENDING_APPROVAL, AMENDMENTS_PROPOSED, ARCHIVED, EXPIRED — **24 total**). Separate `clearanceStatus` axis: NOT_APPLICABLE / AWAITING_DOCUMENTS / DOCUMENTS_UNDER_REVIEW / CLEARANCE_READY_FOR_BOOKING / SELF_CLEARED / ACTIVE_SHIPMENT_IN_PROGRESS. | +| Rate | `DRAFT → PENDING_APPROVAL → LIVE` (+ SUPERSEDED) | +| Train schedule | `DRAFT → SCHEDULED → DISPATCHED → ARRIVED` (+ CANCELLED) | +| Warehouse inventory | export: `RECEIVED → STORED → RESERVED → READY_FOR_LOADING → LOADED → DISPATCHED → UNLOADED_AT_DJIBOUTI_PORT` · import: `UNLOADED → READY_FOR_PICKUP → DELIVERED` (READY_FOR_PICKUP may also → STORED / DISPATCHED) | +| First-mile | `PAYMENT_PENDING → READY_TO_TRANSIT → IN_TRANSIT → RECEIVED_TO_PORT` (auto-created legs enter at READY_TO_TRANSIT) | +| Last-mile | `PAYMENT_PENDING → READY_TO_TRANSIT → IN_TRANSIT → DELIVERED` (auto-created legs enter at READY_TO_TRANSIT) | +| Invoice | `DRAFT / PENDING / ISSUED → PARTIALLY_PAID → PAID` (+ EXPIRED, CANCELLED, REFUNDED; **OVERDUE defined but never set**) | +| Interchange doc | `DRAFT → GENERATED → ACKNOWLEDGED / DISPUTED / CANCELLED` | +| Empty container return | `RETURNED → ASSIGNED_STORAGE → DOCUMENTATION_CLEARED → WAGON_ALLOCATED → TRANSPORTED_TO_DJIBOUTI → HANDOVER_ISSUED → COMPLETED` | + +--- + +## 16. Notable gaps & caveats (verified against code) + +- **Counter-sign is direction-based, not customs-based** (bookings *and* contracts): `IMPORT`/`EXPORT` open a + clearance gate even with customs off; only `DOMESTIC` skips it. The customs flag only selects the clearance + document set. +- **`SELECTED_FOR_BATCH` is set by the batch engine, not at operation-accept** — train accept sets + `FULLY_EXECUTED` first. +- **`FacilitiesModule` is never imported into `AppModule`** — `/api/facilities` is **unmounted / dead** (not + reachable at all). `tracking`, `maintenance`, `fuel` carry no permission decorator but *are* mounted — behind + the **global JwtGuard**, just not permission-gated. +- **`tracking_events` has no writer anywhere** — `TrackingService.record()` is never called, so the customer + tracking timeline is unpopulated. Only staff `train_checkpoint_events` are written (by `recordCheckpoint`/`arrive`). +- **First-mile paid-flag listener is a dead code path** — `@OnEvent("firstmile.invoice.paid")` (no underscore) + never fires because the emitted event is `first_mile.invoice.paid`; the first-mile `paid` flag is never flipped by settlement. +- **Invoice `OVERDUE` status is never set** — no cron/setter transitions to it, though it is in the enum and `OPEN_STATUSES`. +- `POST /api/internal/payments/mark-paid` is `@Public` with **no service auth** (ServiceAuthGuard removed; noted in code). +- **Demo settlement shortcut** in `billing.payInvoice` bypasses real webhooks (TODO/remove) — invoices settle inline at pay-time. +- Server does **not** validate upload size/MIME (client-side only); it enforces *required-doc presence* at clearance. +- Dead / unwired FE calls: `trains/:id/details` (no route), portal `consignments` service hits `/consignments` without `/api`, and list endpoints `bookings/my`, `queues/:queue`, `by-company/customer-view` have no active caller. +- NOTE: The repo `CLAUDE.md` states auth is stubbed/unwired — **this is stale**: auth is live via `@tria-plc/api-common` (global `JwtGuard` + `HasActiveDelegationGuard` `APP_GUARD`s). + +--- + +*Generated from `apps/edr-freight-api`, `apps/edr-freight-web/{portal,backoffice}`, `apps/edr-payment-api` +on branch `freight/feat/fixes-v1`. Reflects code at scan time; regenerate after major module changes.*