TraqRoute - Real-Time Route Optimization & Delivery System

A high-performance, scalable delivery route optimization system built with Java + Quarkus, implementing advanced algorithms for real-time driver assignment and route optimization.

🚀 Features

Core Functionality

• Order Management: Place, track, and manage delivery orders with pickup/delivery locations
• Driver Assignment: Intelligent driver-to-order matching using distance, capacity, and availability
• Route Optimization: Real-time route calculation using Dijkstra's and A* algorithms
• Live Tracking: WebSocket-based real-time location tracking for drivers and orders
• Priority Queue: Smart order prioritization based on urgency, time, and special requirements

Advanced Algorithms

• Graph-based Pathfinding: Efficient shortest path algorithms (Dijkstra, A*)
• Spatial Indexing: Geohash-based location indexing for fast proximity searches
• Load Balancing: Intelligent driver load distribution and capacity management
• Dynamic Re-routing: Real-time route recalculation for traffic and new orders

Technical Stack

• Backend: Java 17 + Quarkus 3.6.3
• Database: PostgreSQL with spatial queries
• Cache: Redis for fast lookups and session management
• Real-time: WebSocket for live tracking
• Containerization: Docker + Docker Compose
• Monitoring: Prometheus + Grafana

🏗️ Architecture

📁 Project Structure

traqroute-backend/
├── src/
│   ├── main/
│   │   ├── java/com/traqroute/
│   │   │   ├── api/                 # REST API Resources
│   │   │   ├── domain/              # Business Models & Entities
│   │   │   ├── service/             # CDI Services
│   │   │   ├── persistence/         # JPA Repositories
│   │   │   ├── algorithms/          # DSA: Graphs, Pathfinding
│   │   │   ├── queue/               # Redis Queue Handlers
│   │   │   ├── cache/               # In-Memory/Redis Cache
│   │   │   ├── websocket/           # WebSocket Real-Time
│   │   │   └── utils/               # Utilities
│   │   ├── resources/
│   │   │   ├── META-INF/
│   │   │   │   └── persistence.xml  # JPA Configuration
│   │   │   └── application.yaml     # Quarkus Config
│   │   └── Dockerfile               # Backend Container
│   └── test/                        # Unit & Integration Tests
├── docker-compose.yaml              # Local Development Setup
├── README.md
└── system-design.md                 # System Design Document

🛠️ Setup & Installation

Prerequisites

• Java 17 or higher
• Maven 3.8+
• Docker & Docker Compose
• Git

Quick Start

1. Clone the repository

   git clone https://github.com/yourusername/traqroute-backend.git
   cd traqroute-backend

2. Start the infrastructure

   docker-compose up -d postgres redis

3. Run the application

   # Development mode
   ./mvnw quarkus:dev
   
   # Or build and run
   ./mvnw clean package
   java -jar target/quarkus-app/quarkus-run.jar

4. Access the application

   • API: http://localhost:8080
   • OpenAPI Docs: http://localhost:8080/openapi
   • Health Check: http://localhost:8080/health

Full Development Environment

# Start all services including monitoring tools
docker-compose --profile tools --profile monitoring up -d

# Access additional tools:
# - pgAdmin: http://localhost:5050 (admin@traqroute.com / admin123)
# - Redis Commander: http://localhost:8081
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000 (admin / admin123)

📚 API Documentation

Core Endpoints

Orders

POST   /api/orders              # Create new order
GET    /api/orders              # List all orders
GET    /api/orders/{id}         # Get order details
PUT    /api/orders/{id}/status  # Update order status
DELETE /api/orders/{id}         # Cancel order

Drivers

POST   /api/drivers             # Register driver
GET    /api/drivers             # List all drivers
GET    /api/drivers/{id}        # Get driver details
PUT    /api/drivers/{id}/location # Update driver location
PUT    /api/drivers/{id}/status # Update driver status

Routes

POST   /api/routes              # Create optimized route
GET    /api/routes              # List all routes
GET    /api/routes/{id}         # Get route details
PUT    /api/routes/{id}/optimize # Re-optimize route

Tracking

GET    /api/tracking/orders/{id} # Get order tracking info
GET    /api/tracking/drivers/{id} # Get driver tracking info
WS     /ws/tracking             # WebSocket for real-time updates

Example Usage

Create a Delivery Order

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "John Doe",
    "customerPhone": "+1234567890",
    "pickupLocation": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "123 Main St, New York, NY"
    },
    "deliveryLocation": {
      "latitude": 40.7589,
      "longitude": -73.9851,
      "address": "456 Broadway, New York, NY"
    },
    "priority": 2,
    "specialInstructions": "Fragile items"
  }'

Register a Driver

curl -X POST http://localhost:8080/api/drivers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@traqroute.com",
    "phone": "+1987654321",
    "vehicleType": "Van",
    "licensePlate": "ABC123",
    "currentLocation": {
      "latitude": 40.7505,
      "longitude": -73.9934,
      "address": "789 5th Ave, New York, NY"
    }
  }'

🔧 Configuration

Environment Variables

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=traqroute
DB_USERNAME=traqroute
DB_PASSWORD=traqroute123

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Application
QUARKUS_PROFILE=dev
JAVA_OPTS=-Xmx1g -Xms512m

🧪 Testing

Run Tests

# Unit tests
./mvnw test

# Integration tests
./mvnw verify

# Test coverage
./mvnw jacoco:report