Logistics, Delivery & Proof of Delivery (PoD) Architecture

Related docs: Delivery Tracking · Order Lifecycle · Data Models · API Design

Pakashop employs a robust logistics management and Proof of Delivery (PoD) system. This system integrates individual delivery agents, independent courier company fleets, and platform administrators under a secure validation model compliant with the Zambian Electronic Communications and Transactions (ECT) Act No. 4 of 2021.

1. Legal Compliance (Zambia ECT Act 2021)

Under the Zambian ECT Act, electronic signatures are granted the same legal status and admissibility as wet ink signatures. Pakashop's Proof of Delivery implements a two-tier framework to ensure compliance:

Standard Electronic Signatures: Captured dynamically on the Delivery Agent's device using a touch-canvas digital signature pad.
Advanced Electronic Signatures: Enhanced on the server side using SHA-256 tamper-evident cryptographic hashing. This binds the captured signature image, order details, and precise timestamp into an immutable record.

PoD Hash = SHA-256(orderId + signatureImageBase64 + signatoryName + capturedAt)

If any transaction details or signatures are altered post-confirmation, the recalculated hash fails to match the stored hash, immediately alerting operators to potential tampering.

2. Onboarding Workflow & Role Enforcement

To preserve platform integrity and separate commercial interests, the platform enforces strict role constraints and application state checks.

2.1 Role Constraints

Platform Admins: Cannot register as delivery partners or merchants.
Shop Owners (Merchants): Cannot apply to become delivery agents to prevent shipping conflicts of interest.
Existing Delivery Agents: Locked out from applying again. If an application status is PENDING or ACTIVE, they cannot submit a duplicate application.
FLEET_MANAGER: Courier company admin role; can manage sub-agents but cannot be a sub-agent themselves.

2.2 The Application States

The application lifecycle is tracked via the DeliveryAgent database status field:

3. Two-Tier Proof of Delivery Flow

Deliveries are confirmed directly on the agent's device via a two-tier verification workflow:

3.1 Tier 1: PIN Verification

Upon ordering, the buyer receives a unique 6-digit PIN via SMS/Email/WhatsApp.
At delivery, the agent enters this PIN. The monolith validates it. If correct, it returns signatureRequired: true along with a generated signatureId token.
The PIN is single-use and expires 24 hours after order creation.

3.2 Tier 2: Signature Capture

A canvas modal appears. The signing recipient inputs their full name and optional telephone number (essential for proxy/receptionist deliveries).
The user signs on the touch pad.
On save, the Base64 image and stroke logs are sent to the capture API. The backend computes the secure hash and advances the order state to DELIVERED.
The DeliveryConfirmation record stores:
- signatureImage: Cloudinary URL of the captured signature
- signatureHash: SHA-256 tamper-evident hash
- signatoryName: Name of the person who signed
- signatoryPhone: Optional phone number of the signatory
- confirmedAt: Timestamp of confirmation

4. Courier Company Fleet Management

Courier Companies operate as independent delivery partners. They have access to a custom logistics operations dashboard where they can manage their own fleet:

PACRA Business Validation: During registration, companies must provide their legal registered name and business registration number, subject to admin verification.
Sub-agent Onboarding: Courier admins (FLEET_MANAGER role) can invite and bind individual drivers to their company. Adding a sub-agent upgrades the driver user's role to DELIVERY_AGENT and automatically links them to the parent company.
Removal Pipeline: Courier admins can dissolve bindings, removing sub-agents from their company fleet instantly.

5. Technical API Directory

5.1 Frontend Wrapper Library (`src/lib/delivery.js`)

Decoupled functions wrapping logistics backend endpoints:

Function	Method & Endpoint	Description
`submitDeliveryApplication`	`POST /api/v1/delivery/apply`	Submits agent or company applications.
`getMyAgentProfile`	`GET /api/v1/delivery/agent/me`	Retrieves current user's delivery partner profile.
`agentToggleAvailability`	`PATCH /api/v1/delivery/agent/availability`	Toggles driver availability state.
`agentGetDeliveries`	`GET /api/v1/delivery/agent/deliveries`	Fetches active shipments assigned to the driver.
`agentConfirmDelivery`	`POST /api/v1/delivery/agent/confirm`	Performs Tier-1 PIN verification.
`captureDigitalSignature`	`POST /api/v1/delivery/signature/:id/capture`	Performs Tier-2 digital signature capture.
`courierGetAgents`	`GET /api/v1/delivery/courier/agents`	Lists courier company sub-agents.
`courierAddAgent`	`POST /api/v1/delivery/courier/agents`	Registers a sub-agent to the company.
`courierRemoveAgent`	`DELETE /api/v1/delivery/courier/agents/:id`	Deletes a company sub-agent.
`adminGetApplications`	`GET /api/v1/delivery/admin/applications`	Lists pending delivery partner applications.
`adminGetAgents`	`GET /api/v1/delivery/admin/agents`	Lists all verified delivery agents.
`adminApproveAgent`	`PATCH /api/v1/delivery/admin/agents/:id/approve`	Approves a pending application.
`adminRejectAgent`	`PATCH /api/v1/delivery/admin/agents/:id/reject`	Rejects application with a specific reason.
`adminSuspendAgent`	`PATCH /api/v1/delivery/admin/agents/:id/suspend`	Suspends an active delivery partner.
`adminActivateAgent`	`PATCH /api/v1/delivery/admin/agents/:id/activate`	Re-activates a suspended delivery partner.

6. Frontend Route Directory

Route	Role	Description
`/apply/delivery-agent`	Any (not SHOP_OWNER, not existing agent)	Partner onboarding page (dual-tab: individual / company, drag-and-drop document uploaders)
`/agent/dashboard`	DELIVERY_AGENT	Field driver view (availability controls, secure shipments feed, PIN/signature validation panels)
`/courier/dashboard`	FLEET_MANAGER	Fleet operator portal (metrics widgets, sub-agents listing directory, register driver forms)
`/platform-admin/delivery/applications`	PLATFORM_ADMIN	Admin panel (review pipelines, type filters, document previews, re-activation controls, custom rejection reason modal sheets)
`/platform-admin/delivery/agents`	PLATFORM_ADMIN	All agents management (suspend, activate, view performance)

7. Settlement Trigger

Upon successful delivery confirmation (Tier 2 complete):

Order status → DELIVERED
OrderItem.settlementStatus → RELEASABLE (per shop)
pakashop-settlement service (port 3016) processes batch payouts
Vendor receives funds via their configured ShopPayoutMethod

For internal use only. Do not distribute outside Pakashop engineering.

1. Legal Compliance (Zambia ECT Act 2021)​

2. Onboarding Workflow & Role Enforcement​

2.1 Role Constraints​

2.2 The Application States​

3. Two-Tier Proof of Delivery Flow​

3.1 Tier 1: PIN Verification​

3.2 Tier 2: Signature Capture​

4. Courier Company Fleet Management​

5. Technical API Directory​

5.1 Frontend Wrapper Library (src/lib/delivery.js)​

6. Frontend Route Directory​

7. Settlement Trigger​