edr-platform/docs/freight-platform/SYSTEM-FLOW.md

# EDR Freight — How the System Works (Step by Step)

A plain-language walkthrough of the whole customer journey:

**Onboarding → Contract → Clearance → Booking → Schedule → Delivery**

Every step shows its branches. Read the arrows (`→`) as "then". Read **IF** blocks as the different paths.

---

## 1) Onboarding

> Goal: register the company so it can make bookings. The wizard has **9 steps** in this order.

```
1. Nationality   2. Role/Operation   3. Company info   4. Personnel (GM)
5. Contact person   6. Verify phone (OTP)   7. Power of Attorney (optional)
8. Documents   9. Business license per profile
```

### Step 1 — Pick nationality

```
Foreign  OR  Ethiopian
```
(stored on the company: `nationality = "foreign" | "ethiopian"`)

### Step 2 — Pick operation type(s)

You may pick **more than one**. Each one becomes its own *profile* with its own approval + license.

```
Importer  OR  Exporter  OR  Freight Forwarder
(importer | exporter | freight_forwarder)
```

### Steps 3–7 — Fill company + people

- **Company:** TIN (auto-looked-up from eTrade), name, email, phone, address (region/zone/woreda/kebele/house), VAT, FAN.
- **Personnel:** General Manager name / email / phone.
- **Contact person:** name / phone (+ optional position, email).
- **Verify:** SMS OTP sent to the contact phone — must enter the 6-digit code.
- **Power of Attorney:** all optional.

### Step 8 — Upload company documents → **THIS IS WHERE THE PATH SPLITS**

The required documents depend **only on nationality** (NOT on operation type).

```
IF Ethiopian  → upload:
      • TIN Certificate
      • Commercial License
      • National ID

IF Foreign    → upload:
      • TIN Certificate
      • Investment License
      • National ID
      • Passport
```

All are required (1 file each, pdf/jpg/png, ≤10 MB).

### Step 9 — Business license per profile

For **each** operation type you picked, upload that profile's business/trade license (1+ files each).

### After onboarding finishes

```
Company status      → "Pending"   (backoffice must approve)
Each profile status → "Pending"

Backoffice approves each profile one by one
   → profile status = "active", gets a reference (e.g. IM-00001 / EX-00001)
   → only then can that profile create contracts/bookings
```

**Branch summary**

| Nationality | Company documents required |
|-------------|----------------------------|
| Ethiopian   | TIN Certificate · Commercial License · National ID |
| Foreign     | TIN Certificate · Investment License · National ID · Passport |

> Operation type changes **nothing** in the document set — only adds one business-license card per profile.

---

## 2) Contract

> Goal: agree the terms (route, cargo, price) and sign. Only an **active profile** can do this.

### Create — the wizard (4 steps)

```
Step 0  Setup        operation direction (import/export/intercity),
                     contract kind (ONE_TIME vs GENERAL),
                     new vs renewal, service type, currency,
                     first/last mile, customs-clearing on/off, equipment return
Step 1  Cargo+Route  container sizes OR bulk commodity, hazardous/reefer flags,
                     origin & destination yard, extra routes (GENERAL only)
Step 2  Documents    required onboarding docs + any contract-specific uploads
Step 3  Review       check everything, see quotation, submit (or save draft)
```

Two key choices made here decide later paths:

```
contract kind:        ONE_TIME  (one shipment at a time)
                      GENERAL   (ship many times over a validity window)

customs clearing:     ENABLED   → Path B  (Global Logistics clears for you)
                      DISABLED  → Path A  (you self-clear)  — for IMPORT/EXPORT
                      (DOMESTIC/intercity → no clearance at all)
```

### Status journey (happy path)

```
DRAFT
  → SUBMITTED                       (customer submits; prices frozen)
  → PENDING_APPROVAL                (staff accepts intake, sets validity window)
  → APPROVED                        (approval chain signs: LINE_STAFF → DIRECTOR → CEO)
  → CONTRACT_READY                  (staff generates the contract PDF)
  → SIGNED_CUSTOMER                 (customer signs)
  → counter-sign by staff/director/ceo … then it SPLITS ↓
```

### The counter-sign split → which path?

```
IF customs clearing ENABLED  (IMPORT/EXPORT)        → PATH B
     status → AWAITING_CLEARANCE_DOCUMENTS

IF customs clearing DISABLED (IMPORT/EXPORT)        → PATH A (self-clear)
     status → AWAITING_CLEARANCE_DOCUMENTS

IF DOMESTIC / intercity (no clearance)              → NO CLEARANCE
     status → CONTRACT_ACTIVE (GENERAL) or FULLY_EXECUTED (ONE_TIME)
     → customer can book a shipment right away (skip to section 4)
```

**Side branches at any review stage**

```
staff requests changes → CHANGES_REQUESTED → customer edits → SUBMITTED again
staff rejects          → REJECTED
customer/staff cancels → CANCELLED
GENERAL contract later → renew → RENEWAL_DRAFT (copies the old contract)
```

---

## 3) Clearance

> Only happens for IMPORT/EXPORT contracts. Two paths. The loop is the same idea:
> **customer uploads → reviewer approves or queries → customer re-uploads → … → finalize.**

### Who reviews?

```
PATH A  (self-clear, customs DISABLED)  → reviewed by OPERATIONS team
PATH B  (customs, customs ENABLED)      → reviewed by GLOBAL LOGISTICS (GL)
```

### The status sub-states

```
AWAITING_CLEARANCE_DOCUMENTS   customer must upload
CLEARANCE_UNDER_REVIEW         reviewer is checking
CLEARANCE_READY_FOR_BOOKING    (Path B) done — GL will make the booking
SELF_CLEARED                   (Path A) done — customer will make the booking
```

### The review loop (both paths)

```
1. Customer uploads all required documents
        → status = CLEARANCE_UNDER_REVIEW
        → each document = PENDING

2. Reviewer goes document by document:
        APPROVE  → that document = APPROVED
        QUERY    → that document = QUERIED (note required)
                   → contract drops back to AWAITING_CLEARANCE_DOCUMENTS
                     (only the queried doc needs re-uploading; approved ones stay)

3. Customer re-uploads the queried document → back to step 2

4. When ALL required documents are APPROVED → finalize (below)
```

### PATH A — self-clear (Operations)

```
documents the CUSTOMER uploads (examples):
   import: customs declaration (IM4/IM5), import release, duty/tax receipt,
           delivery order, supporting doc
   export: customs declaration (EX3/EX8), export release, transit (T1), supporting doc

no output documents in Path A.

Operations finalize  (POST .../clearance/ops-finalize)
   requires: every required doc APPROVED
   → clearanceStatus = SELF_CLEARED
   → contract status = CONTRACT_ACTIVE (GENERAL) or FULLY_EXECUTED (ONE_TIME)
   → CUSTOMER creates the booking  (section 4)
```

### PATH B — customs (Global Logistics)

```
documents the CUSTOMER uploads (examples):
   import container: commercial invoice, packing list, import license,
                     certificate of origin, freight cost, bill of lading,
                     VGM*, release order*
   export container: booking confirmation, invoice, packing list,
                     shipping instruction, bank permit, export license,
                     VGM letter*, railway bill, delegation letter
   (* = required)

then GL uploads OUTPUT documents (container only):
   import: IM4 (required), IM5 (optional), transit screenshot
   export: EX3 (required), EX8, export release, T1

GL finalize  (POST .../clearance/finalize)
   requires: every required customer doc APPROVED
             AND every required output doc uploaded
   → clearanceStatus = CLEARANCE_READY_FOR_BOOKING
   → GL (not the customer) creates the booking  (section 4)
```

### Cycles (GENERAL contracts)

A **cycle** is one clearance round. ONE_TIME contracts have a single cycle (#1). GENERAL contracts open a new cycle each time they need clearance before the next shipment.

> Clearance (section 3) is **pre-booking**. After GL creates the booking, the work continues as **GL Phase 2** — see section 4b.

---

## 4) Booking

> Goal: turn a cleared/executed contract into an actual shipment. **Who creates it depends on the path.**

```
PATH A / DOMESTIC  → the CUSTOMER creates the booking
PATH B (customs)   → GLOBAL LOGISTICS creates the booking on the customer's behalf
```

### The gate (who's allowed)

```
IF contract has customs clearing (Path B):
     only GL,  and only when clearanceStatus = CLEARANCE_READY_FOR_BOOKING

IF no customs (Path A / DOMESTIC):
     customer (or staff), and only when contract is FULLY_EXECUTED / CONTRACT_ACTIVE
```

### Booking wizard (customer self-booking — 7 steps)

```
0 Operation type     import / export / intercity (+ FF variants)
1 Contract type      ONE_TIME vs GENERAL ; new vs renewal
2 Service & mile     service type, currency (USD/ETB), first/last mile,
                     equipment return, customs agent / customs on-off
3 Cargo details      container list (type, qty, VGM) OR bulk weight,
                     hazardous / refrigerated flags
4 Route              origin & destination yard;
                     scheduledDate REQUIRED for ONE_TIME (estimate only),
                     NOT set for GENERAL (a day is chosen later)
5 Documents          per-booking document uploads
6 Review             notes, submit
```

### Booking status journey

```
DRAFT
  → generate price → SUBMITTED            (if price changed: PRICE_CHANGED_PENDING_CONFIRM → confirm → SUBMITTED)
  → PENDING_APPROVAL                       (staff accept intake)
  → APPROVED / CONTRACT_READY              (approval chain)
  → SIGNED_CUSTOMER → counter-sign … SPLIT ↓

IF clearance applies → AWAITING_DOCUMENTS → DOCUMENTS_UNDER_REVIEW → CLEARANCE_READY
IF no clearance      → FULLY_EXECUTED directly
```

> The booking has its **own** document clearance loop, mirroring the contract one
> (upload → APPROVED/QUERIED → re-upload → finalize). Re-uploading a queried doc
> resets it to PENDING. Booking proceeds only when all required docs are APPROVED.

### Pricing & payment

```
price generated from rule engine + live rates, converted to chosen currency (USD/ETB)
customer pays (Telebirr) once the booking is FULLY_EXECUTED / SELECTED_FOR_BATCH
payment status: PENDING → VERIFICATION_IN_PROGRESS → PAID (or FAILED)
```

---

## 4b) Global Logistics — Phase 2 (after the booking exists)

> Customs (Path B) shipments keep moving through GL after booking. This phase is
> a **milestone timeline** plus a set of **structured GL actions**. The customer
> only watches and, when asked, pays / uploads a duty slip.

### Milestone timeline

When GL creates the booking, the system seeds the **post-booking milestones**
for that direction (import ~15, export ~11). Each is `PENDING → COMPLETED`.

```
Import (post-booking):  WAGON_REQUESTED → FREIGHT_PAYMENT_SETTLED → WAGON_ALLOCATED
   → GATEPASS_GRANTED → READY_FOR_LOADING → LOADED → DEPARTED_FROM_DJIBOUTI
   → ARRIVED_ETHIOPIA → OFFLOADED → T1_CLOSED → RISK_ASSIGNED
   → IMPORT_RELEASE_GRANTED → IMPORT_PROCESS_COMPLETED
   → STORAGE_INVOICE_RAISED → EXIT_NOTE_GENERATED

Export (post-booking):  WAGON_REQUESTED → FREIGHT_PAYMENT_PENDING → FREIGHT_PAYMENT_SETTLED
   → WAGON_ALLOCATED → CARGO_ARRIVED → READY_FOR_LOADING → LOADED
   → DEPARTED_TO_DJIBOUTI → ARRIVED_AT_DJIBOUTI → GATEPASS_GRANTED → OFFLOADED
```

Each milestone has an **owner**: ET (GL Ethiopia), DJ (GL Djibouti), OPS (Operations),
CUST (customer). Backoffice shows the timeline with a **Complete** button on the
next pending step; the customer portal shows the same timeline **read-only**.

### GL actions (the structured part)

Plain "Complete" covers most steps. These carry extra data, so they have their
own UI cards on the backoffice **milestones page** (`GlActionsPanel`):

```
Station routing   → route shipment to a station yard (+ bind GL staff)        (GL US-02)
Customs risk      → assign GREEN / YELLOW / RED → completes RISK_ASSIGNED
Duty & tax        → GL advises amount + declaration serial → completes
                    DUTY_TAXES_ADVISED → customer uploads slip → DUTY_TAX_PAID
GL documents      → upload DO / RO / T1 / import release / interchange /
                    final declaration → auto-completes the matching milestone
Cargo exception   → log SEAL_BROKEN / CONTAINER_OPENED / CONTAINER_DAMAGED /
                    FLUID_LEAKING with photos → alert GL Ethiopia             (GL US-07)
```

**Doc-triggered milestones:** uploading the mapped document completes the
milestone automatically — no separate click:

| Upload (code) | Completes milestone | Who |
|---------------|---------------------|-----|
| `delivery_order` | DO_COLLECTED | GL DJ |
| `release_order` | RELEASE_ORDER_SECURED | GL DJ |
| `t1_transport_document` | T1_CLOSED | GL ET |
| `import_release` | IMPORT_RELEASE_GRANTED | GL ET |
| `full_in_interchange` | OFFLOADED | GL DJ |
| `final_declaration` | IMPORT_PROCESS_COMPLETED | GL ET |
| `duty_tax_receipt` | DUTY_TAX_PAID | **Customer** |

### ET ↔ DJ handoff

```
DEPARTED_FROM_DJIBOUTI (import)  → lead returns to GL Ethiopia + Operations
DEPARTED_TO_DJIBOUTI   (export)  → lead moves to GL Djibouti
```
Ownership region is encoded per-milestone in the catalog; notifications fire on
handoff (notification module pending).

### What the customer does in Phase 2

```
watch the timeline (read-only)
pay duty/tax  → upload payment slip  (only when GL advised it)
pay freight   → Pay button on the booking when batch-selected
that's all — every other step is GL / Ops / Terminal
```

### Where it lives (Phase 2)

| Area | Files |
|------|-------|
| Milestone seed/advance | `api/.../contracts/clearance-milestone.service.ts`, `clearance-milestone.catalog.ts` |
| GL actions (risk/duty/station/docs/incident) | `api/.../contracts/gl-operations.service.ts`, `dto/gl-operations.dto.ts`, `entities/clearance-incident.entity.ts` |
| Endpoints | `api/.../contracts/contracts.controller.ts` (`bookings/:id/risk` · `/duty` · `/station-assign` · `/documents` · `/incidents` · `/duty-slip`) |
| Backoffice UI | `backoffice/.../pages/contracts/BookingMilestonesPage.tsx`, `components/contracts/ClearanceMilestoneTimeline.tsx`, `components/contracts/gl-actions/*` |
| Portal UI | `portal/.../bookings/BookingDetailPage/components/ShipmentTrackingCard.tsx` |

### Still out of scope (per design doc §18)

Demurrage auto-calc & storage invoicing, finance AP closure, multimodal
(sea/air + MTO/OBL/HBL), truck waybill PDF + POD signing. `STORAGE_INVOICE_RAISED`
and `EXIT_NOTE_GENERATED` exist as **manual milestones** only — no fee engine yet.

---

## 5) Schedule (Operations)

> Goal: put the booking on a train (or dispatch by road). Day-level pooling — the
> customer picks a **day**, the batch engine assigns the actual **train** later.

```
1. Customer requests operation        pick a day that has an OPEN departure
        → OPERATION_REQUEST_PENDING

2. Operations review the request → one of:
        ACCEPT          → FULLY_EXECUTED (enters the train batch pool)
                          (road service instead → ROAD_DISPATCH_PENDING, section 6)
        REQUEST_CHANGES → OPERATION_CHANGES_REQUESTED (note required; customer resubmits)
        ADJUST_PRICE    → OPERATION_PRICE_PENDING_CONFIRM
                          (customer confirms new price → pool, or rejects → changes requested)

3. Batch engine (cron) groups bookings by (origin yard, destination yard, day):
        allocates to open train schedules by priority score
        → SELECTED_FOR_BATCH, assigns trainScheduleId, sets payment deadline

4. Payment (if not already paid) → PAID

5. IN_TRANSIT  → COMPLETED
```

### Wagon math

```
wagons per booking = sum over containers of (qty × wagonsPerUnit), rounded up
```

---

## 6) Delivery / Last mile

```
IF road service:
     ACCEPT → ROAD_DISPATCH_PENDING (skips the train pool)
     billed by KM, dispatched by truck (First-Mile operations)

IF first/last mile chosen at booking:
     pickup + delivery addresses captured; equipment return = WITH / WITHOUT
     last-mile statuses: PAYMENT_PENDING → READY_TO_TRANSIT → IN_TRANSIT → RECEIVED_TO_PORT
```

---

## The whole thing on one page

```
ONBOARD
  nationality ─┬─ Ethiopian → TIN + Commercial License + National ID
               └─ Foreign   → TIN + Investment License + National ID + Passport
  pick profiles (importer/exporter/FF) → upload license per profile
  → backoffice approves profile → profile ACTIVE

CONTRACT
  wizard (setup → cargo+route → docs → review) → SUBMITTED
  → staff accept → approval chain → CONTRACT_READY → customer sign → counter-sign
  → SPLIT:
       customs ENABLED  (import/export) → PATH B clearance
       customs DISABLED (import/export) → PATH A clearance
       DOMESTIC                         → no clearance, ready to book

CLEARANCE  (import/export only)   loop: upload → approve/query → re-upload → finalize
  PATH A: Operations review → SELF_CLEARED            → CUSTOMER books
  PATH B: GL review + GL output docs → READY_FOR_BOOKING → GL books

BOOKING
  created by CUSTOMER (Path A / domestic) or GL (Path B)
  price → pay → (its own doc clearance if applicable) → ready to schedule

GL PHASE 2  (customs/Path B, after booking)
  milestone timeline: wagon → pay → allocate → load → depart → handover
    → arrive → offload → T1 close → risk → release → complete
  GL actions: station routing · risk (G/Y/R) · duty advise · DO/RO/T1 upload · incident
  customer: watch read-only · upload duty slip · pay freight

SCHEDULE
  request a day → Operations accept → batch engine → train assigned
  → pay → IN_TRANSIT → COMPLETED
  (road service → ROAD_DISPATCH_PENDING → truck)
```

---

### Where this lives in the code (quick map)

| Area | Key files |
|------|-----------|
| Onboarding | `portal/.../components/onboarding/OnboardingWizardDialog.tsx`, `api/.../companies/companies.service.ts`, `api/src/seed/file-upload-settings.seeder.ts` |
| Contract | `portal/.../contracts/new-contract-form/`, `api/.../contracts/contract-transition.service.ts`, `entities/contract.entity.ts` |
| Clearance | `api/.../contracts/contract-clearance.service.ts`, `contract-clearance.util.ts`, `portal/.../contracts/ContractClearancePanel.tsx` |
| Booking | `portal/.../bookings/new-booking-form/`, `api/.../bookings/booking-transition.service.ts`, `contract-booking.service.ts` |
| Schedule | `api/.../train-scheduling/booking-batch.service.ts`, `backoffice/.../operations/FirstMilePage.tsx` |