Hyperlocal Last-Mile Delivery Tracking System
A production-grade REST API for D2C businesses to manage local deliveries end-to-end — from order creation to final delivery, with real-time tracking, agent assignment, and role-based access control.
Personal Project
2026
Logistics / Backend
Spring Boot · MySQL JWT
Challenge
D2C businesses need reliable delivery infrastructure but most lack a backend to enforce shipment state transitions, assign agents fairly under load, and expose role-appropriate APIs. The challenge was to build this from scratch — handling concurrency, audit trails, and multi-role security without over-engineering.
Results
Built a fully functional REST API handling the complete delivery lifecycle — from order creation to final delivery. Implemented production-grade patterns including concurrency control, role-based access, and business analytics — all as a first-year MCA student.
7
Shipment lifecycle states
3
JWT auth roles
0
Race conditions via pessimistic locking
Process
Shipment Lifecycle Design: Defined a strict 7-state lifecycle (CREATED → ASSIGNED → PICKED_UP → IN_TRANSIT → DELIVERED / FAILED / CANCELLED) with enforced valid transitions. Every status change is logged with actor, timestamp, and reason — full audit history.
Agent Auto-Assignment: Built load-based agent selection using a JPQL aggregation query that counts active deliveries per agent. Wrapped in @Transactional with pessimistic locking to prevent two orders being assigned to the same agent simultaneously.
Business Analytics API: Exposed reporting endpoints for avg delivery time, on-time rate, and per-agent success rate using JPQL GROUP BY with custom DTO projections — no native SQL, fully portable.
Security Architecture: JWT-secured with 3 roles — BUSINESS_OWNER, DELIVERY_AGENT, and customer. Customers use enumeration-safe public UUIDs for tracking — no login required, no internal IDs exposed.
Tech Stack: Java 17 · Spring Boot 3 · Spring Security · Spring Data JPA · MySQL · JWT · Swagger UI · Railway
Conclusion
This project goes beyond basic CRUD — it enforces real business rules through state machines, handles concurrent requests safely with pessimistic locking, and exposes clean role-separated APIs. The architecture is designed to scale and the codebase is structured for maintainability and extension.