# NexGate Shipping Service — Build Plan Development

How we build docs/shipping/SHIPPING_SERVICE_DESIGN.md (the "design", § numbers below point to it).
Status: plan agreed to start, nothing built yet. Built on the Location Service (done: wards, shop locations,
user addresses, frozen places). 
 Ground rules for every step 
 
 Talk first, then build — each step starts with a short talk on its details, then code. 
 Code standard : new top-level package shipping_service/ (same level as location_service/ ), the project's
controller / service / service/impl / payload / entity / repo shape, no boilerplate, comments only where needed. 
 Existing responses : add fields; reshape only when agreed (dev phase) and always recorded. 
 Every change recorded in commerce_logistics_changes.md — before / after, examples, app to-do. 
 Design doc kept true — any decision that changes during a step is updated in the design. 
 Settings : fixed rules in properties ( shipping.* ), per-shipper agreement settings in the database (§6.7.1). 
 Money : every money move goes through the ledger; every step that moves money ends with the ledger balance check. 
 Tested live locally after each step (like the location steps), using the worked scenarios (§17) as test cases. 
 Phase-0 hooks (§15b) are built in from the start: attempt records, failure reason codes, the extra statuses,
timers as data, reverse legs allowed — even though their rules come later. 
 
 The order at a glance 
 
 
 
 Step 
 Delivers 
 Real-world result after the step 
 
 
 
 
 0 
 Foundations 
 nothing visible; ground ready 
 
 
 1 
 Pickup, end to end (with codes and "✓ It's what I ordered") 
 buyers can buy and collect at the shop 
 
 
 2 
 Native shipper registration (KYC + Service Setup basics) 
 delivery businesses can sign up 
 
 
 3 
 Door coverage, pricing, ETA 
 businesses describe where / how much 
 
 
 4 
 Engine: estimation + quotation (single door leg) 
 buyers see real delivery costs 
 
 
 5 
 Cart / checkout / agreement, escrow per part 
 buyers pay real delivery 
 
 
 6 
 Job flow: offers, codes, statuses, release 
 first real door-to-door deliveries 
 
 
 7 
 Reassignment, switching, cancelling, bulky mismatch 
 unhappy-but-common cases handled 
 
 
 8 
 Reliability, reviews, auto-pause, upcoming orders 
 trust and planning 
 
 
 9 
 Stations (single leg) 
 intercity: collect at a station 
 
 
 10 
 Multi-shipper chains 
 shop → bus → door 
 
 
 11 
 Group purchase and installments 
 shipping inside group / installment buys 
 
 
 12 
 Free shipping (seller rules + campaigns) 
 "Free delivery" badges and filter 
 
 
 13 
 Bolt integration 
 boda on demand in town 
 
 
 14 
 Admin dashboard (screens) 
 ops tooling — last 
 
 
 later 
 Notifications set · unhappy paths (§15a/b) · staging deploy 
 after the build 
 
 
 
 
 Step 0 — Foundations 
 Goal: everything later steps stand on, with no behaviour change. 
 
 Package shipping_service/ with sub-packages from §2 (empty shells added as each step needs them). 
 shipping.* properties with every value from §6.7.1 (read through one settings class). 
 Shared opening hours (§6.3): weekly ranges, special days, temporarily closed, cut-off, EAT, overnight;
"is open at", "next opening", "add opening hours" helpers. Attached to shops now (§6.4): shop hours endpoints,
"Open now / Opens Sat 09:00" on shop responses; shop pause modes (keep selling / stop orders, SHOP_CLOSED ). 
 Escrow table : part (ITEMS / LEG), legId , orderId filled, provider payee (§12.1) — new columns only,
current payments keep working (they are "ITEMS" parts). 
 Product bulky field (§8.1) — default false; category pre-tick later. 
 File Thunder : new upload types business document (private) and business logo (separate repo, small). 
 Codes service : 4 random digits, hashed, never logged, 5 tries → locked, regenerate (§11). Replaces the old
 DeliveryConfirmation code generator (and its plain-code log line). 
 
 Check: existing checkout / orders / cart-escrow tests still pass; shop hours + pause visible; a code can be
generated, verified, locked after 5 wrong tries, and never appears in logs. 
 Step 1 — Pickup, end to end 
 Goal: a buyer can buy, the seller prepares, the buyer collects with a code, money is released on confirmation. 
 
 Move Step-4 e_commerce/fulfillment (JSON) into shipping_service/fulfillment as a table ; orders link to it
(§2, §3.5). Frozen places stay inside the record. 
 Shipping agreement entity (§4.8): shipping_agreement + parties + changes; states DRAFT → PENDING → AGREED →
DONE / CANCELLED. For pickup the only parties are the buyer and the seller. Escrow parts move only on agreement
events from here on. 
 Order flow: seller accepts (24 opening hours, else auto-cancel + refund) → Ready → buyer told → pickup at
the counter : buyer's code, seller enters it → collected (§3.1, §10). 
 "✓ It's what I ordered" releases all escrow parts in one transaction; "⚠ Report a problem" freezes them (§12.2). 
 Account setting: code or "received" button (§11). 
 Pickup statuses placed → accepted → ready → collected → completed (+ cancelled / expired); optional pickup
time (shop opening hours, inside the window; reminder that morning). 
 14-day collection expiry with reminders (§3.1). Cancel before the seller accepts (§3.4a). Seller cancel at once
(pop-up "I have already informed the buyer"; pickup before collected, delivery before Ready). 
 Recent pins recorded after payment , not at checkout (§4.4). 
 Admin endpoints needed from now: manual release / refund of an escrow part (§6.7.2) — SUPER_ADMIN , reason, audit log. 
 
 Check: scenario A (§17) live: pay → accept → ready → code → collected → confirm → seller paid; 14-day expiry; seller cancel
refunds; cancel before accept refunds; problem report freezes; admin release works and is logged. 
 Step 2 — Native shipper registration 
 Goal: a delivery business can sign up and get approved automatically. 
 
 KYC (§6.2 part 1): name, contact phone, office location (pin), business licence (file + number + expiry,
unique number), director's NIDA (file + number), LATRA (file + number + expiry) → auto-approved KYC_APPROVED . 
 Service Setup basics (§6.2 part 2): profile (logo, description, WhatsApp, email, badge), service type
(door / station), hours (shared piece, default Mon–Sat 08:00–18:00), limits (max value, bulky + extra,
response window, heads-up). Setup checklist endpoint. 
 Statuses KYC_APPROVED → LIVE ⇄ PAUSED , SUSPENDED ; documents private (owner + admin). 
 "Delivery business" mode in the app (owner only, §6.6) — endpoints for the owner's own business. 
 Admin endpoints: suspend / lift (§6.7.2). 
 
 Check: register with all documents → auto-approved; duplicate licence number refused; documents not visible to
others; checklist shows what's missing; suspend / lift logged. 
 Step 3 — Door coverage, pricing, ETA 
 Goal: a business says where it works, how much, how long — and goes LIVE. 
 
 Location helpers (in location_service ): regions → districts → wards lists + search; coverage outline for the map. 
 Coverage (§7.1): ticked areas (region / district / ward), trips WITHIN_EACH / WITHIN_AND_ACROSS ,
"both ends inside", fast area-code matching (the spec's second core function, areaMatch ). 
 Pricing (§8.1): distance bands (price + time each, ×1.3, last band = max distance), flat, value add-on ladder
 
 max value, bulky extra, rounding up to 100. 
 
 
 Goes LIVE automatically when service type + coverage + pricing exist. 
 Delivery commission fee type (0%) in the fee table + per-shipper override with start date (§6.7.1). 
 
 Check: the §7.1 crossing table (Sinza → Mikocheni with WITHIN_EACH vs ACROSS…) as tests; band and add-on maths
incl. rounding; business flips to LIVE when complete. 
 Step 4 — Engine: estimation + quotation (single door leg) 
 Goal: buyers see real delivery options and costs. 
 
 Engine (§9): where → who (coverage) → filter (distance, value, bulky, hours / cut-off, paused) → cost + ETA →
clean-up (dominated, outliers 3×) → labels 💰 ⚡ ⭐ (⭐ = price + time at launch) → order, top 5, fairness. 
 ETA (§8.2): from "shop ready", ranges, closed hours. 
 Estimation POST /api/v1/shipping/estimations (§4.5): cost {from,to} , eta {from,to} , pickup area;
Redis cache shop-area → buyer-area (1 h). 
 Quotation (§4.1): live options for a shop's parcel and a destination (§4.2: saved / recent / pin; station
recognition comes with step 9). 
 Product detail: live quotation for the viewer's address. 
 
 Check: scenario L (cards) and the engine walk-throughs from the master guide (A, B, E) reproduce; cache hit
on the second call; closed shipper shifts ETA instead of disappearing. 
 Step 5 — Cart, checkout, agreement, escrow per part 
 Goal: buyers pay the real delivery cost; money split into items + leg. 
 
 Cart (§4.3, §4.4): one destination per cart, per-shop quotation held 5 days , add-to-cart fulfillment +
 dropoff , defaults for a new shop, unsaved pin on the cart, re-quote on changes. 
 Checkout → agreement (§4.1, §4.8) with its legs (each leg escrow part points to one): editable on the checkout screen until paid (re-quote, wallet re-check), locked
once paid . Buy-now uses the sheet's quotation. 
 Escrow per part (§12.1): items part → seller, leg part → shipper owner; release all on confirm. 
 Seller fee on items + tax only ; delivery commission from the leg (§8.3). 
 shippingByShop now real costs (replaces the 0 placeholder). 
 What the app keeps vs the server (§4.6) honoured. 
 
 Check: scenario B up to payment: escrows created per part with the right payees and fees; quotation older
than 5 days refreshed; edit at checkout re-quotes; ledger balance check passes. 
 Step 6 — Job flow, codes, delivery 
 Goal: the first real door-to-door delivery from offer to release. 
 
 Seller accepts → heads-up ; Ready → offer with response window (counted while open), closed-shipper
4 h rule (§10). 
 Ready pop-up : "I have packed it well" + "label / number is on the package" (recorded). 
 Parcel number created when the seller accepts (QR label generated by the app, or written on the box); scanned / typed at pickup → "✓ yours / ✗ wrong parcel";
shippers see the parcel, never the order (§11, §6.6). 
 Shipper: accept / reject (reason), timeout; active job steps; pickup code (seller verifies) and delivery
code (shipper submits) or the buyer's button (§11); optional handover photos. 
 Shipper accept = signs the agreement ; all signed → AGREED, parcel moves (§4.8). 
 Statuses door ladder (§3.2) incl. heading to the shop + phase-0 statuses. 
 Release on "✓ It's what I ordered": items → seller, leg → shipper (one transaction). 
 Shipper app endpoints for offers / jobs / earnings (§6.6), live push. 
 
 Check: scenario B end to end; scenario M (a shipper's day) step by step; timeout counted; codes locked
after 5 tries. 
 Step 7 — Reassignment, switching, cancelling, bulky mismatch 
 Goal: the common unhappy-but-normal cases. 
 
 Reassignment (§10a): rejection / timeout → that leg only; tiers 1 km → same district → buyer ; same-or-cheaper
and not slower = automatic (escrow re-pointed, difference refunded); dearer / none → buyer decides; loop guard
3 per order ; buyer silent 24 h → pickup ; chain safety net 24 h ; free-shipping caps recalculated; history kept. 
 Switching (§3.4): pickup → delivery (fresh quotation, pay, offer at once if Ready); delivery → pickup (before any
shipper accepted, refund). 
 Cancelling (§3.4a): shipping-only until pickup — free before heading to the shop , wasted-trip fee (50% / Bolt's
charge) after; whole order when the chain failed. 
 Agreement changes (§4.8): propose → affected parties approve → default on silence; destination change 
(accept new cost / keep old price / decline; no withdraw after pickup). 
 Bulky mismatch (§8.4): report before pickup, bulky-only reassignment, seller pays difference + 50% wasted trip,
auto-flag after 2. 
 Badly packed refusal (§8.5): before pickup, photo, seller repacks + Ready again, seller pays 50% wasted trip. 
 Admin endpoints: force reassign / cancel (§6.7.2). 
 
 Check: scenarios D, F, G, H, N, O, P ; loop guard; silent buyer → pickup after 24 h; ledger balanced after every
adjustment. 
 Step 8 — Reliability, reviews, auto-pause, upcoming orders 
 
 Reliability counters (acceptance, on time, failed, broke binding) and auto-pause levels with the §14 table,
grace period 10 offers, reasons shown. 
 Reviews like shops, verified only, owner replies, moderation (§14); shown in quotations. 
 Two-way private ratings (shipper rates buyer / seller). 
 Upcoming orders on the shipper dashboard, area-only until accepted (§6.6). 
 Real delivery times recorded (for after-launch ETA). 
 
 Check: the §14 trigger table as tests (2 / 3 missed, 3rd pause in 7 days → suspended…); new shipper not paused
inside the grace period; upcoming card hides the exact pin until accepted. 
 Step 9 — Stations (reached by a door leg) 
 
 Stations (§7.2): pins with counter name, phone, hours; ≥ 1 per ticked area; lines ; reach 30 km 
(per business override). 
 Station-pair table (price + time, both ways, pre-filled pairs) (§8.1). 
 Handover points (§7.2a): leg 1 always starts with a collection at the shop (option A) — either the station
business collects from shops (areas + flat fee, 0 = free; one leg) or a door shipper brings it to the station
(the two-leg chain door → station, built here); buyer collects at the destination station (station staff enter the
buyer's code). Step 10 extends it to 3 legs, editing and re-confirms. 
 Station ladder (§3.3); quotation meeting-point recognition ("collect at Mbeya Bus Stand", §4.2). 
 
 Check: a Mbeya → Morogoro trip as boda → bus (two legs) and as a bus company collecting free (one leg, ranked
cheapest); no door shipper at the shop → no station route; pin within 1 km of a station
offers "collect there"; empty pair = not offered. 
 Step 10 — Multi-shipper chains 
 
 Chain building (§4.7): up to 3 legs, meeting points within 1 km, always next to single-leg options. 
 Quotation editing per leg: stop early, swap a leg's shipper, change a meeting point. 
 All legs offered at Ready, nothing moves until all accept ; binding after accept ; re-confirm when an
accepted leg's time moves > 4 h (§10a 7a). 
 Shipper → shipper handover: "handed over" / "received" + that handover's code, optional photo (§11). 
 One escrow part per leg ; release all together (§12). 
 
 Check: scenarios C, D, E with three legs; one leg rejecting while others accepted; re-confirm triggered by a 
 
 4 h move. 
 
 Step 11 — Group purchase and installments 
 
 Group (§5): each member's own fulfillment and fee with their payment; refunds on fail / withdraw; moves with a
transferred payment; price frozen at payment. 
 Installments (§5): immediate = fee with the down payment; layaway = choose and pay after the last instalment
(reuses switch-to-delivery). 
 
 Check: scenarios J and K . 
 Step 12 — Free shipping 
 
 Seller rules (areas, minimum, cap, product override) and NexGate campaigns (areas, dates, cap, audience, shops,
budget reserved at payment, auto-stop) (§13). 
 Stacking, the cheapest qualifying option free, faster pays the difference; campaign ledger account; seller share
from the items part at release. 
 Estimation freeDelivery + card badge + "Free delivery to my area" search filter. 
 
 Check: scenario I ; campaign budget never overspent under parallel checkouts; refund returns budget. 
 Step 13 — Bolt integration 
 
 Adapter (§6.5): OAuth2 token cache, estimations (boda, non-bulky, in-city), book at Ready (re-estimate, held price
= max + 2%), cancel, webhooks (3 IPs + token) and polling fallback, state mapping, tracking link + driver details. 
 Bolt ledger account , monthly settlement record, receipt differences; kill-switch and daily spend limit 
(§6.7); seller pays a shop no-show. 
 Built and tested in Bolt's sandbox first. 
 
 Check: sandbox flow (estimate → create → states → completed → receipt); NO_DRIVER_FOUND → reassignment; spend
limit blocks new Bolt quotations; kill-switch hides Bolt immediately. 
 Step 14 — Admin dashboard (last) 
 Screens on top of the existing admin endpoints (§6.7.3): shippers + KYC documents, Bolt status and settlement,
operations board, campaigns, reports (by area), audit log, STAFF_ADMIN / SUPER_ADMIN split. 
 After the build 
 
 New dedicated shipping notifications (one set, after the shipping service). 
 Unhappy paths (§15a / §15b): auto-confirm window, delivery attempts + office hold, returns, disputes. 
 Staging / production : PostGIS image + CREATE EXTENSION , ward file, settings — at deployment. 
 After-launch items (§16). 
 
 Dependencies 
 0 ─► 1 ─► 2 ─► 3 ─► 4 ─► 5 ─► 6 ─► 7 ─► 8
 │ ├─► 9 ─► 10
 │ ├─► 11
 │ ├─► 12
 │ └─► 13
 └─────────────────────► 14 (last)
 
 Steps 9, 11, 12, 13 can be reordered after step 6 (each only needs the single-leg flow). 10 needs 9.