The Courier Management System (CMS) is a backend RESTful application built using Spring Boot that manages courier operations such as shipment creation, courier assignment, tracking, authentication, and administration. This document provides a high-level yet complete functional and technical specification of the system, intended to guide an LLM or a developer in generating the full project.
The system is designed as a modular, scalable, role-based backend suitable for real-world courier or logistics platforms.
- Provide a complete backend for courier operations
- Role-based access control (Admin, Customer, Courier)
- Shipment lifecycle and real-time tracking
- Clean REST API design
- Production-ready architecture
- Frontend UI
- Real-time GPS tracking (simulated via updates)
- External integrations (SMS/email gateways are abstracted)
| Role | Description |
|---|---|
| ADMIN | Manages users, couriers, shipments, reports |
| CUSTOMER | Creates and tracks shipments |
| COURIER | Accepts assignments and updates shipment status |
Each authenticated user has exactly one role.
Base authentication entity. Every actor in the system is a user.
Key fields:
- id
- email (unique)
- password (hashed)
- role (ADMIN, CUSTOMER, COURIER)
- active
Represents a customer sending shipments.
Key fields:
- id
- userId (FK → User)
- name
- phone
- address
Represents a delivery agent.
Key fields:
- id
- userId (FK → User)
- vehicleType
- status (AVAILABLE, BUSY, OFFLINE)
The central business entity.
Key fields:
- id
- trackingNumber (unique, public-facing)
- senderCustomerId
- receiverName
- receiverPhone
- pickupAddress
- deliveryAddress
- weight
- status
- createdAt
CREATED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED
↘️ CANCELLED
Links a courier to a shipment.
Key fields:
- id
- shipmentId
- courierId
- status (ASSIGNED, ACCEPTED, REJECTED)
Immutable events that record shipment progress.
Key fields:
- id
- shipmentId
- status
- location
- remarks
- timestamp
- JWT-based authentication
- Role-based authorization via Spring Security
- Password hashing (BCrypt)
- Token-based stateless sessions
- Customers can create shipments
- Admins can view all shipments
- Shipments generate a unique tracking number
- Shipment status can only move forward (except cancellation)
- Admin assigns courier to shipment
- Courier must accept or reject assignment
- Only accepted couriers can update shipment status
- Each shipment status update creates a tracking event
- Public tracking via tracking number
- Tracking history is immutable
- Manage users
- View shipment statistics
- Monitor courier availability
POST /api/v1/auth/register
POST /api/v1/auth/login
GET /api/v1/auth/me
POST /api/v1/customers
GET /api/v1/customers/{id}
GET /api/v1/customers/{id}/shipments
POST /api/v1/couriers
GET /api/v1/couriers
PATCH /api/v1/couriers/{id}/status
POST /api/v1/shipments
GET /api/v1/shipments/{id}
GET /api/v1/shipments
PATCH /api/v1/shipments/{id}/status
POST /api/v1/assignments
PATCH /api/v1/assignments/{id}/accept
PATCH /api/v1/assignments/{id}/reject
GET /api/v1/track/{trackingNumber}
GET /api/v1/shipments/{id}/tracking-history
POST /api/v1/track/{shipmentId}/update
Controller → Service → Repository → Database
- Controller: Request/response mapping
- Service: Business logic
- Repository: JPA data access
com.example.courier
│
├── config
├── controller
├── dto
│ ├── request
│ └── response
├── entity
├── repository
├── service
├── exception
├── util
└── CourierApplication
- Entities are never exposed directly
- Separate DTOs for request and response
- Validation via
@Valid
Example:
- ShipmentRequest
- ShipmentResponse
Centralized via @ControllerAdvice
Handled cases:
- ResourceNotFoundException → 404
- UnauthorizedException → 401
- ValidationException → 400
Tables:
- users
- customers
- couriers
- shipments
- assignments
- tracking_events
Relationships:
- User 1–1 Customer / Courier
- Shipment 1–Many TrackingEvents
- Shipment 1–1 Assignment
| Endpoint | Access |
|---|---|
| Create shipment | CUSTOMER |
| Assign courier | ADMIN |
| Update shipment status | COURIER |
| Track shipment | PUBLIC |
- Stateless APIs
- Pagination for list endpoints
- API versioning (
/api/v1) - OpenAPI / Swagger documentation
- Java 17+
- Spring Boot
- Spring Security
- Spring Data JPA
- PostgreSQL / MySQL
- Lombok
- MapStruct
- Flyway
- Swagger (OpenAPI)
Future enhancements:
- Payment integration
- Notification services (email/SMS)
- Real-time tracking via WebSockets
- Microservices split
This document fully defines the structure, behavior, APIs, and architecture of the Courier Management System. It is intended to be sufficiently detailed for an LLM or developer to generate:
- Database schema
- Entity models
- Controllers, services, repositories
- Security configuration
- End-to-end working backend
End of Specification