A delivery-first commerce & logistics platform

Build a delivery-first commerce platform that lets multiple vendors sell and fulfill goods across industries while operating a flexible delivery network for both last-mile and long-haul movement.

Problem statement

Existing commerce systems treat delivery as an afterthought. This platform positions delivery as the core operating model — vendors sell goods while the platform manages fulfillment, route planning, dispatch, tracking, and proof of delivery.

Core value propositions

• Unified commerce platform for multiple vendors
• Delivery orchestration across last-mile and long-haul flows
• Industry-aware workflows for medicine, agriculture, hospitality, imported cargo
• Visibility for customers, vendors, drivers, dispatchers, administrators
• Scalable from small local fleets to large regional transport networks

Strategic goals

1. Support multi-vendor commerce with centralized operations
2. Offer reliable delivery execution for urgent and scheduled shipments
3. Support regulated sectors such as medicine and temperature-sensitive cargo
4. Enable onboarding of new vendors and industries with configurable workflows
5. Evolve into a marketplace plus logistics operating system

Non-goals for phase 1

• Full autonomous fleet management
• Advanced AI routing optimization
• Multi-country regulatory compliance beyond the initial target geography
• Full ERP integration in the first release

Benchmarked against the operating models of Amazon (marketplace + fulfilment + advertising), Jumia (African marketplace + own logistics + wallet + agent network), Jiji (classifieds/C2C supply + promoted listings), and Uber Direct/Connect (delivery-as-a-service + peer parcel send). Ziggo combines all four on a delivery-first backbone.

Objectives

Delivery-first commerce where fulfilment is the core competence · one system for last-mile + long-haul across any industry · first-class support for low-trust, cash-heavy markets · a two-sided marketplace · multiple revenue streams · logistics that can be sold as a service.

Marketplace models supported

Fulfilment models supported

Business capabilities

Discovery & merchandising: search/filter/recommendations · featured-offer / "Buy Box" selection when vendors compete on the same item · promoted / sponsored listings (Jiji TOP/Boost, Amazon Sponsored) · vendor storefronts. Ordering & payments: multi-vendor cart · cash-on-delivery as a first-class flow · card/transfer/platform wallet · escrow (funds released only on POD) · BNPL/financing (future) · promos/referrals/loyalty. Fulfilment & logistics: all models above · own fleet + third-party + on-demand matching · platform fulfilment centres · Delivery-as-a-Service API for external merchants. Trust & safety: vendor/seller verification & moderation · ratings & reviews · buyer-protection guarantee (Amazon A-to-z style) · seller protection · escrow-backed settlement · fraud/abuse controls · buyer-seller chat. Growth & monetisation: membership/loyalty (Prime-style) · advertising · referrals · agent-assisted commerce (JForce-style) for offline/low-trust buyers · vendor subscription tiers. Seller tools: seller centre with catalog, multi-location inventory, pricing, promotions, payouts, analytics & account health.

Competitive benchmark — what Ziggo adopts

Success metrics (KPIs)

Marketplace: GMV, take-rate, active vendors & retention, repeat rate, conversion. Logistics: on-time & first-attempt success rate, delivery time by mode, cost per order, fleet utilisation, exception rate. Trust: NPS/CSAT, dispute & return rate, resolution time. Financial: revenue per merchant, ad/promoted revenue, COD share & reconciliation accuracy, payout timeliness.

Eleven core use cases, each specified with actors, pre/postconditions, and main / alternate / exception flows. Index below; two representative full specs follow.

Full flows for all 11 use cases are in the source document.

Shared enumerations

Role              = customer | vendor | driver | dispatcher | operationsManager
                    | financeUser | supportAgent | admin
IndustryType      = medicine | agriculture | hospitality | importedCargo
                    | generalRetail   (seed records, extensible via DB)
DeliveryMode      = lastMile | longHaul
OrderStatus       = pending | pendingCompliance | confirmed | inFulfillment
                    | completed | cancelled | disputed
DeliveryJobStatus = created | unassignable | assigned | pickedUp | inTransit
                    | delivered | failed | returned
VehicleType       = bike | van | truck | refrigeratedTruck
HazardClass       = none | flammable | biohazard | controlledSubstance | fragile
VerificationStatus= pending | verified | expiring | expired | rejected

Relationship overview

• A Vendor manages many Products; a Customer places many Orders
• An Order contains many OrderItems and is fulfilled by one or more DeliveryJobs via one FulfillmentRequest
• A DeliveryJob is assigned one Driver + one Vehicle, concludes with one ProofOfDelivery, may raise ExceptionCases
• One RoutePlan may serve multiple DeliveryJobs — the structural key to long-haul consolidation
• Each PaymentTransaction produces one or more SettlementLedger entries

Class diagram (textual)

User <|-- CustomerProfile / VendorProfile / DriverProfile / DispatcherProfile

VendorProfile   "1" -- "0..*" Product
CustomerProfile "1" -- "0..*" Order
Order           "1" -- "0..*" OrderItem
Order           "1" -- "1"    FulfillmentRequest
FulfillmentRequest "1" -- "0..*" DeliveryJob
DeliveryJob     "0..*" -- "1"  RoutePlan
RoutePlan       "1" -- "0..*"  RouteStop
DeliveryJob     "1" -- "0..1"  ProofOfDelivery
DeliveryJob     "0..1" -- "1"  DriverProfile / Vehicle
Order           "1" -- "0..*"  PaymentTransaction
PaymentTransaction "1" -- "0..*" SettlementLedger

High-level layers

Client applications → API layer → domain services → workflow/orchestration → data & integrations.

Order flow

submit order → validate address/stock/pricing → accept & route to fulfillment
→ dispatch creates delivery job → driver app receives assignment
→ delivery events published → proof of delivery stored → settlement + notifications

Architectural principles

• Event-driven for operational workflows · API-first for integrations
• Role-based access control · configurable rules for sector-specific operations
• Observability from day one

Security considerations

Authentication & MFA for operational accounts · secure document storage · audit logging for changes and approvals · role-based permissions across finance, dispatch, and vendor operations.

Revenue streams

Marketplace commission · delivery fee · freight/long-haul charges · optional vendor subscription tiers · priority/express surcharge · value-added services (cold-chain, signature, insurance, customs brokerage) · settlement-float interest.

Commission by vertical

Configurable per vendor and per industryType. Starting defaults — require market validation before Phase 1 sign-off.

Delivery pricing

Last-mile: base fee + per-km within zone, with multipliers for cold-chain, signature/ID, off-hours, surge. Long-haul: base + (distance × rate) + (weight/volume × rate) + stop_surcharge × stops, with route consolidation reducing per-order cost.

Worked example — medicine, ₦10,000 goods, last-mile, cold-chain

Illustrative only — currency, tax, and rate cards need finance confirmation.

Medicine / pharmaceutical

Verified pharmacy license before listing · controlledSubstanceSchedule flag with order-time prescription/ID checks · cold-chain enforcement (refrigerated vehicles only, temperature at delivery) · batch/lot + expiry tracking for recalls · signature & recipient-ID at handover · extended audit retention.

Agriculture / produce

Produce grade & harvest date · farm-origin traceability · time-to-delivery SLAs for perishables · farm pickup as an origin stop type · optional inspection/phytosanitary certificates.

Hospitality (food & beverage)

Tight delivery-window SLA with at-risk flagging · kitchen prep-time input feeding dispatch timing · age verification for alcohol · heat-retention flag · allergen/ingredient metadata.

Imported cargo / freight

Shipment documents (bill of lading, commercial invoice, packing list, certificate of origin) · HS codes · customs stages as explicit statuses · hazmat class matched to vehicle/driver certification · bonded warehouse as a stop type · multi-order route consolidation.

Cross-cutting

Stricter access control & retention for PII and health-adjacent data · immutable audit trail for flagged orders · one configurable identity-verification capability reused across verticals · license verification at vendor onboarding varying by industryType.

Numeric targets are Phase-1 proposals for validation, not committed SLAs.

Performance

Availability

Other targets

• Security: TLS everywhere, encryption at rest, separate key management for sensitive fields, RBAC + field-level checks, MFA for operational roles, no raw card storage (tokenized gateway)
• Retention: by sensitivity — extended for controlled-substance / customs records; tracking-ping geo data short-lived (~90 days) then aggregated
• Observability: correlation ID spanning order → settlement; business metrics; alerts on dispatch backlog, stale jobs, payment failures, cold-chain breaches
• DR: near-zero RPO for transactional data; RTO in minutes for the dispatch path
• Localization: multi-currency assumed; flexible address formats · Accessibility: WCAG 2.1 AA

A recommendation to react to, not a final decision — confirm against team expertise, cloud relationships, and launch jurisdiction.

Every phase produces documented evidence: requirement documents, design artifacts, backlog items, test evidence, deployment evidence.

Recommended execution order — superseded in sequencing by the single-go-live decision (see Milestone Plan), retained as the capability roadmap.

1. Core commerce foundation
2. Delivery orchestration engine
3. Driver & dispatcher operations
4. Finance & settlement
5. Industry-specific modules (now data-driven configuration)
6. Optimization & scale

Scored on likelihood × impact → severity. Owners are role-based (team not yet staffed).

Register shows the highest-severity risks; medium risks R-08, R-10–R-13 are in the source document.

10 epics · ~60 stories. Representative epics shown with full acceptance material in the source.

E4 — Order & fulfillment

E5 — Delivery orchestration

E7 — Payments & settlement

Critical path

M0 → M1 → M2 → M3 → (M4, M5, M6 overlap) → readiness review → SINGLE GO-LIVE

longest tail: M6 (long-haul consolidation, S5.5 XL)
              M5 (gated on confirmed jurisdiction + legal sign-off)

M4/M5/M6 can overlap once M2/M3 dependencies exist, but all three must complete before go-live — the main cost of building all at once is that long-haul and regulated capabilities now sit on the critical path to first revenue.

Module boundaries

Conventions

• API: REST/JSON, URL-versioned; Bearer JWT with role/permission claims; consistent error envelope; cursor pagination
• Idempotency: keys on order placement, payment capture, driver status updates — critical on flaky mobile networks
• Data: UUID keys; money as integer minor units + currency; forward-only migrations; append-only ledger & sensitive records
• Eventing: at-least-once with idempotent consumers; per-entity ordering where sequence matters
• Third parties: PaymentGateway, RoutingProvider, NotificationChannel, IdentityVerification — internal interfaces with swappable adapters

Testing strategy

Unit (pricing/commission, status transitions) · integration per module against real Postgres · contract tests for provider adapters · E2E on the critical path (order → dispatch → deliver → settle) · high-rigor coverage for Payments/Settlement and capability-matched dispatch · security review + load test before go-live.

Detailed runtime design realizing the Phase 1 conventions — architecture, the dynamic industry/compliance engine, sequence flows, and state machines. (The end-to-end sequence is drawn at the top of this page.)

The dynamic compliance engine

Industry behavior is data, resolved at runtime — there is no per-vertical code:

Product create ─► requiredFields(industry)  → validate product has all required keys
Order placed   ─► checkOrder(order)         → {handlingFlags, blockers}
Dispatch       ─► requiredCapabilities(job) → filter vehicles/drivers whose
                                              capabilitySet ⊇ required set

Capability matching is one generic set-superset test reused across cold-chain, hazmat, signature, and age-verification — not per-vertical branches. Adding an industry is inserting two rows.

Order state machine

pending ─validate─► confirmed ─fulfil─► inFulfillment ─complete─► completed
   │                    │                     │
   ├─hold─► pendingCompliance ─resolve─────────┤
   └─reject/fail─► cancelled                   └─dispute─► disputed

DeliveryJob state machine

created ─assign─► assigned ─pickup─► pickedUp ─depart─► inTransit ─deliver─► delivered
   │                                                        │
   ├─no capacity─► unassignable                             ├─fail─► failed ─retry─► assigned
   └────────────────────────────────────────────────────────┴─return─► returned

Concrete PostgreSQL 15+ schema (with PostGIS). UUID keys; money as bigint minor units + currency; timestamptz UTC; append-only financial/audit tables.

Keystone: the dynamic industry & compliance tables

industry_type ── compliance_profile_id ─► compliance_profile
                                            ├ required_product_fields text[]
                                            ├ requires_cold_chain / hazmat /
                                            │ signature / age_verification / customs
                                            ├ required_license_type
                                            ├ default_commission_bps
                                            └ sensitive_data_class · retention_days

Both are tables, not enums — seed data editable by admins at runtime. Adding an industry is an INSERT, not a deploy.

Product: typed columns + validated JSONB

product( ... unit_price bigint, currency char(3), hazard_class hazard_class_t,
         requires_cold_chain bool,
         attributes jsonb )   -- industry-specific: hs_code, produce_grade,
                              -- controlled_substance_schedule, allergen_info ...
CREATE INDEX ... USING GIN (attributes);

The ComplianceEngine validates attributes contains every key the industry's required_product_fields demands — no per-vertical column explosion.

Integrity highlights

• settlement_ledger & audit_log are append-only (UPDATE/DELETE revoked at the DB role level)
• idempotency_key + domain_event (transactional outbox) back the eventing design
• Balances are derived by summing ledger entries; a reconciliation worker asserts they tie out per period
• PostGIS geography columns on address and delivery_zone for nearest-driver & zone lookups

REST over HTTPS, JSON, snake_case, base path /api/v1. Bearer JWT with role/permission claims. Idempotency keys on money-or-physical-world POSTs. Consistent error envelope with a correlation ID.

Representative endpoints

POST /api/v1/delivery-jobs/{id}/assign
{ "driver_id":"...", "vehicle_id":"..." }
409 → { "code":"dispatch.capability_mismatch",
        "details":{ "required":["cold_chain"], "vehicle_has":[] } }

Topology

Internet → CDN/WAF → Load balancer
   ├─► API pods (stateless, autoscale on latency)
   └─► Worker pods (dispatch, routing, notifications, settlement, outbox)
        │
   Postgres(+PostGIS) primary+replica · Redis · Managed queue · S3 · Secrets mgr
        │
   Adapters → PaymentGateway · RoutingProvider · SMS/Push · IDVerify

Key decisions

• Two workload classes scaled independently — API pods (bursty customer traffic) vs worker pods (continuous dispatch); a lunch-hour order spike can't starve deliveries in progress
• Managed containers (Fargate/Cloud Run), not Kubernetes yet; Terraform for all three environments (local · staging · production)
• Routing/consolidation isolated on its own worker pool; Dispatch is the likely future service extraction
• Append-only enforced at the DB grant level; separate KMS key for compliance-sensitive fields; card data tokenized at the gateway
• CI/CD gates migrations before rollout; feature flags let incomplete capabilities ship dark under build-all-at-once
• DR: near-zero RPO, minutes RTO on the order/dispatch path, with restore drills

Six portals, each with two parallel clients over the same REST API — a Next.js web version and a Kotlin (Android, Compose + Material 3) mobile app. Below is the full feature catalog per portal. Tags: (new) = needs a new entity/endpoint; B1–B4 = build stage.

1 · Customer portal

Account: register/login (OTP/social) · saved addresses & payment methods · notification prefs. Discovery: browse by category/industry/vendor · search + filters · product detail · vendor storefronts · wishlists (new) · recommendations. Ordering: multi-vendor cart · service level & window · itemized price + surcharges · serviceability check · promo codes · restricted-item prescription/ID flow · COD · scheduled/recurring orders (new). Tracking: live status timeline · driver ETA/map · notifications · reschedule. Post-delivery: POD/receipt · ratings & reviews · reorder · refund/return/replacement · support tickets.

2 · Vendor portal

Onboarding & account: business registration & KYC · industry selection (drives required fields) · license upload (regulated) · verification status · team members & roles (new) · payout account · storefront branding.

Catalog & merchandising: product CRUD with media/attributes · compliance-required fields enforced · categories & collections · product variants (size/color/pack) (new) · bundles/kits (new) · publish/schedule · featured/merchandising order · SEO fields · bulk CSV import/export (new).

Orders & fulfillment: order queue accept/reject/auto-accept · order detail (masked customer info) · fulfillment & delivery monitoring · split/partial fulfillment · picking/packing slips · returns & replacements. Pricing & promotions: per-product pricing · bulk price update · promotions/discounts (coupons, %/flat, time-boxed) (new: Promotion) · tiered/quantity pricing. Finance: earnings dashboard (sales, commission, net) · settlement & payout status · invoices/statements. Subscriptions & licenses (doc 23): compare/subscribe/upgrade plans · billing history · license records & renewals. Insights: sales & delivery-performance dashboards · support tickets.

3 · Driver app (mobile)

Account & shift: login + MFA · go online/offline · shift schedule · vehicle & capability profile. Jobs & nav: assigned jobs & accept · job/stop detail · turn-by-turn + ordered stops · long-haul multi-stop (B4) · barcode/QR scan (new). Execution & POD: milestone status (offline-queued, idempotent) · signature & photo · recipient ID/age verification · cold-chain temperature · COD collection. Exceptions: failed attempt/damage/refused/address · contact dispatcher. Earnings: per-job & daily summary · payout status.

4 · Dispatcher portal

Queue & assignment: live queue by zone · manual assign with capability-match enforcement · auto-dispatch oversight & override · bulk assign. Live ops: live map of drivers/jobs/routes · driver status & location · ETA/SLA-at-risk · reroute/reassign. Routing: last-mile single-job · long-haul multi-stop planning & consolidation (B4) · manual route editing. Exceptions & alerts: triage & resolution · stale-job/SLA-breach alerts · customs-hold (cargo). Oversight: fleet/driver availability · dispatch performance reporting.

5 · Admin & operations console

Users & access: users/roles/permissions · MFA policy · support impersonation (audited) (new). Industry & compliance config: create/edit industry types & compliance profiles · restricted/controlled-substance rules. Vendor operations: verification queue · license lifecycle oversight (expiring/expired) · suspend/reinstate. Catalog governance: global categories/taxonomy · listing moderation · attribute schemas per industry. Service config: delivery zones · service levels/SLAs · pricing rules/surcharges · vehicle types & fleet registry. Subscriptions/billing (doc 23): plans & entitlements · subscription revenue. Finance (role-gated): settlement & reconciliation · payout runs · invoices · refunds · financial reports. Support (role-gated): tickets · claims · refund/replacement · customer/vendor lookup. Reporting: sales, delivery, fleet, vendor, exception rates · scheduled exports. Governance: immutable audit-log viewer · platform config & feature flags.

6 · Agent portal (new, 2026-07-08)

JForce-style agents place & manage orders on behalf of offline/low-trust customers and earn commission. Account: onboarding & approval · KYC · territory. Assisted ordering: place an order for a named customer · attribution to the agent. Tracking & payments: track their orders · collect (often cash) & reconcile. Earnings: agent commission, statements, payout status. Customer book: manage served customers. (Epic E16.)

One module for two related per-vendor lifecycles the earlier docs only hinted at: subscriptions (paid vendor plans + entitlements + recurring billing) and licensing (regulatory-permit lifecycle — renewal reminders, auto-suspend on expiry). A Should/build-stage-B2 revenue-enhancement module — not launch-blocking.

Subscriptions: plans & entitlements

Plans are data-driven (like the industry engine). Each plan grants typed entitlements — commission_bps_override, max_active_listings, priority_placement, advanced_analytics. Other modules ask entitlementsFor(vendorId) rather than branching on plan names.

Subscription billing lifecycle

subscribe/trial → active ─(renewal ok)→ active (next period)
                     │
                     ├─(charge fails)→ past_due ─(dunning)─┬─ok→ active
                     │                                     └─exhausted→ suspended
                     └─(cancel_at_period_end)→ active till period end → cancelled

Proration on upgrade/downgrade via the PaymentGateway; subscription revenue recorded in the SettlementLedger alongside commission.

Licensing: permit lifecycle

pending →(admin verifies)→ verified →(near expiry)→ expiring ─(renewed)→ verified
                                 │                          └─(lapses)→ expired → auto-suspend listings
                                 └─(revoked)→ suspended

Turns the compliance engine's point-in-time license check into a managed lifecycle: a scheduled worker fires renewal reminders and auto-suspends listings on expiry. The compliance profile still owns which license an industry requires; this module owns the record and its transitions.

New epic E11 (non-launch-blocking)

Phase 0 — Discovery (complete)

Vision, business & functional requirements, user stories/use cases, domain model, data flow & architecture, SDLC plan, roadmap, business/revenue model, industry compliance, NFRs, technology stack.

Phase 1 — Planning (complete, verified)

Risk register (14 risks) · product backlog (10 epics, ~60 stories) · milestone plan (M0–M6) · technical specification.

Phase 2 — Design & architecture (complete, at gate)

• System design — architecture, compliance engine, sequence & state diagrams
• Data model specification — full PostgreSQL DDL incl. dynamic industry/compliance tables
• API contracts — REST endpoints per module
• Infrastructure plan — topology, environments, scaling, CI/CD, DR

Stakeholder decisions recorded (2026-07-05)

• Build all at once — single go-live; R-02 accepted
• Industry stored dynamically in the DB — data-driven compliance engine
• Phase 1 verified; proceeded to Phase 2 with reconciliation back into Phase 1 docs (5 new entities, Product JSONB attributes)