Hyperlocal.
Multi-Tenant Delivery Management Backend
A multi-tenant delivery backend: customers create shipments, the API assigns the least-loaded available agent, and every status change moves through a state machine into an audit trail. A React frontend covers live tracking and agent dashboards.
- —43 REST APIs across auth, shipments and agents
- —Automated assignment by agent load
- —Delivery state machine with a full audit trail
01
Problem & goal
Small delivery operations had no structured way to manage shipments and agents — assignment was manual and status changes went untracked. Hyperlocal gives them a multi-tenant backend where shipment, agent and auth concerns live behind one API.
02
How it works
- —A customer creates a shipment through the REST API; validation and persistence happen in the shipment service.
- —Assignment checks agent load at dispatch time and ships to the least-loaded available agent.
- —Every status change passes the state machine and is appended to the audit trail.
- —The React frontend shows live shipment tracking and agent dashboards.
Architecture
- Customer
- Auth
- Shipment Svc
- Assignment
- State Machine
- Audit Trail
Only legal delivery transitions are allowed.
VISUALS
Project screens
Shipment tracking
Project screenshot pending
03
Security model
- —JWT authentication with access and refresh tokens.
- —Role-based access control across customer and agent routes.
- —Multi-tenant boundaries enforced in the data layer, not just the UI.
04
Built with
05
Challenges & tradeoffs
Keeping status honest
Free-form status fields let deliveries jump backwards or skip states. The state machine makes invalid transitions impossible instead of merely discouraged.
Fair assignment
Round-robin overloads busy agents. Assignment reads agent load at dispatch time so work lands on whoever can actually take it.
Multi-tenancy at the data layer
Filtering tenant data in application code is fragile — one missed condition leaks another tenant's shipments. Tenant isolation lives in the data layer so it applies uniformly across every query.
06
Decisions
A state machine instead of free-form status fields
A state machine instead of free-form status fields — invalid transitions become impossible, not merely discouraged.
Flyway migrations so every schema change is versioned and reviewable.
Flyway migrations so every schema change is versioned and reviewable.
An audit trail on every status change so any dispatch can be traced after the fact.
An audit trail on every status change so any dispatch can be traced after the fact.
Links
Next