Cloud-native fleet telemetry, dispatch orchestration, and automated billing platform.
Engineered with Java 21, Spring Boot 3, Spring Security, Hibernate, MySQL, and React.
Table of Contents
RouteSphere is an enterprise-grade logistics orchestration and fleet operations engine. In modern freight operations, tracking physical assets across variable routes demands synchronized dispatch workflows, audit-proof billing, preventative vehicle maintenance schedules, and role-enforced telemetry visibility.
RouteSphere addresses these requirements with a modular architecture:
- Dispatch Orchestration: State-driven shipment pipelines coordinating origin-to-destination handoffs, driver allocations, and capacity constraints.
- Telematics & Fuel Audit Logs: Systematic tracking of vehicle odometer readings, fuel consumption expenditures, and scheduled maintenance windows.
- Automated Accounting Workflows: Real-time generation of billing invoices upon delivery completion with email receipt notifications.
- Granular Role-Based Security: Decoupled access policies separating dispatch managers, operational fleet coordinators, and auditing personnel.
Client / Operations Dashboard (React 18 + Vite)
│
▼
┌───────────────────────────┐
│ JWT Auth & RBAC Filter │ ──(Unauthorized)──► HTTP 401 / 403 Forbidden
└───────────────────────────┘
│ (Authenticated Principal)
▼
┌───────────────────────────┐
│ REST Controller Layer │ ──► Swagger / OpenAPI 3.0 Doc Spec
└───────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ SPRING BOOT 3 SERVICE ORCHESTRATION │
│ │
│ 1. Shipment Lifecycle Engine (PENDING -> DELIVERED) │
│ 2. Fleet Allocation & Driver Capacity Validator │
│ 3. Trip Dispatch & Milestone Tracking │
│ 4. Automated Invoice Generation on Fulfillment │
│ 5. Fuel Economy & Telematics Ledger Calculation │
└────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ MySQL Persistence │ │ Resend Mail Gateway │
│ (Hibernate/JPA ACID) │ │ (Trip & Billing Notif)│
└───────────────────────┘ └───────────────────────┘
- Deterministic Trip Transitions: Enforces a strict status flow (
PENDING->ASSIGNED->IN_TRANSIT->DELIVERED->COMPLETED). - Resource Conflict Avoidance: Validates driver readiness, vehicle operational status, and active load assignments before confirming dispatch schedules.
- Shipment Manifest Tracking: Consolidates multi-package consignments against destination waybills and recipient records.
- Odometer & Usage Tracking: Logs vehicle operating metrics to schedule preventative maintenance before mechanical faults cause dispatch downtime.
- Fuel Consumption Ledger: Tracks every fuel log entry (liters, cost per unit, fueling station, driver identity) against trip mileage to calculate operational costs per kilometer.
- Fleet Availability Register: Flags inactive or servicing vehicles to prevent double-booking during dispatch waves.
- Automated Invoice Trigger: Delivery confirmation automatically triggers invoice generation containing freight charges, taxes, and customer bill-to details.
- Payment Settlement Tracking: Maintains payment statuses (
UNPAID,PARTIALLY_PAID,PAID) linked directly to the originating shipment identifier.
- Stateless Security: Intercepts requests via Spring Security filters, verifying HMAC-signed JWT tokens and claims.
- Least-Privilege Authorization: Segregates operational endpoints so drivers, dispatchers, and financial auditors access only their required resources.
- Transactional Dispatch Updates: Emits asynchronous customer notifications via Resend API on key milestones (shipment created, driver dispatched, proof of delivery signed).
- Payment Acknowledgement: Automatically transmits formatted receipts upon invoice settlement.
| Layer | Technologies |
|---|---|
| Backend Services | Java 21, Spring Boot 3.x, Spring MVC, Maven |
| Security | Spring Security 6, Stateless JWT Authentication, BCrypt |
| Database & ORM | MySQL 8.x, Hibernate, Spring Data JPA |
| Operations Dashboard | React 18, TypeScript, Vite, Tailwind CSS |
| API Documentation | Swagger UI, OpenAPI 3.0 |
| Notification Service | Resend API Integration |
| Logging & Monitoring | SLF4J, Logback Structured Logging |
| Containerization | Docker, Docker Compose |
- Java Development Kit (JDK) 21
- MySQL 8.x running locally or via Docker
- Node.js 18+ and npm
- Apache Maven 3.9+
Configure your database and mail credentials in src/main/resources/application.properties:
spring.datasource.url=jdbc:mysql://localhost:3306/routesphere_db?createDatabaseIfNotExist=true
spring.datasource.username=root
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update
jwt.secret=your_secure_256_bit_secret_key_here
jwt.expiration=86400000
resend.api.key=your_resend_api_key# Clone the repository
git clone https://github.com/abhiramaab/RouteSphere.git
cd RouteSphere
# Build and run with Maven
./mvnw clean spring-boot:runThe Spring Boot backend will start on http://localhost:8080.
Access Swagger API documentation at: http://localhost:8080/swagger-ui/index.html.
cd frontend
npm install
npm run devThe frontend dashboard will be available at http://localhost:5173.
Live interactive instance: routesphere.abhiram.tech
POST /api/auth/register- Register new user accountPOST /api/auth/login- Authenticate credentials and obtain JWT bearer token
POST /api/shipments- Create a new shipment manifestGET /api/shipments- List all shipments with status and origin/destination filtersGET /api/shipments/{id}- Fetch shipment details and consignment itemsPUT /api/shipments/{id}- Update shipment milestones and state
POST /api/vehicles- Register vehicle asset (make, model, license, capacity)GET /api/vehicles- Retrieve fleet inventory and operational availabilityPOST /api/drivers- Register certified driver profilePOST /api/fuel-logs- Record fuel expenditure and odometer readingPOST /api/maintenance- Schedule or record maintenance servicing
POST /api/invoices- Generate customer invoice for shipmentGET /api/invoices/{id}- Fetch invoice billing status and total freight breakdownPUT /api/invoices/{id}/pay- Record settlement transaction
RouteSphere/
├── assets/ # Dual-mode logos and architecture assets
│ ├── routesphere-logo-dark.svg
│ └── routesphere-logo-light.svg
├── frontend/ # React 18 & Vite Operations Console
│ ├── src/ # Dashboard views, state hooks, components
│ └── package.json
├── src/main/java/com/RouteSphere/REST/
│ ├── config/ # Security, OpenAPI, and Resend configs
│ ├── controller/ # REST controllers (Auth, Shipments, Fleet)
│ ├── dto/ # Request and Response payload contracts
│ ├── entity/ # JPA Entities (Shipment, Vehicle, Trip, Invoice)
│ ├── exception/ # Global exception handling & error models
│ ├── repository/ # Spring Data JPA repositories
│ └── service/ # Dispatch orchestration & domain logic
├── pom.xml # Maven build dependencies
└── Dockerfile # Container deployment definition