Skip to content

System Architecture

Architecture Diagram

System Architecture
           ┌──────────────────────────────────┐
           │         CLIENT LAYER          │
           │  Web • Mobile • External API  │
           └─────────────────┬────────────────┘
                           │
                           │ HTTPS (TLS 1.3)
                           │
         ┌───────────────────▼──────────────────┐
         │  JAVA API GATEWAY (Port 8080)     │
         │       Spring Boot 3.2.3           │
         ├──────────────────────────────────────┤
         │  • JWT Authentication (HS256)     │
         │  • Request Validation             │
         │  • Fallback Logic (RED signal)    │
         │  • Circuit Breaker Pattern        │
         └───────────────────┬──────────────────┘
                           │
                ┌───────────┴─────────────┐
                │                       │
    ┌────────────▼────────┐   ┌────────────▼────────────┐
    │  HEALTH CHECK     │   │  PREDICTION REQUESTS  │
    │  /health          │   │  /traffic/action      │
    └─────────────────────┘   └─┬───────────────────────┘
                              │
                  ┌────────────▼────────────┐
                  │ INFERENCE SERVICE     │
                  │  (Port 8000)          │
                  │  Python/FastAPI       │
                  ├─────────────────────────┤
                  │ • MAPPO RL Model      │
                  │ • 5-Junction Support  │
                  │ • GRU State Mgmt      │
                  │ • Action Masking      │
                  └────────────┬────────────┘
                              │
                ┌──────────────┴────────────┐
                │                         │
    ┌────────────▼──────────┐   ┌────────────▼────────────┐
    │  LSTM PREDICTOR     │   │  ACTION SELECTION     │
    │  (Port 8001)        │   │  (MAPPO Output)       │
    │  Python/FastAPI     │   │                       │
    ├───────────────────────┤   │ Actions:              │
    │ • Time-series LSTM  │   │ 0: RED                │
    │ • 15-min Forecast   │   │ 1: YELLOW             │
    │ • MAE < 10%         │   │ 2: GREEN              │
    │ • Data Pipeline     │   │ 3: GREEN_EXTENDED     │
    └───────────────────────┘   └────────────┬────────────┘
                                          │
                                          │ Signal State
                                          │
                              ┌────────────▼────────────┐
                              │  RESPONSE TO CLIENT   │
                              │ {                     │
                              │   action: 0-3,        │
                              │   signalState: "RED", │
                              │   confidence: 0.87    │
                              │ }                     │
                              └─────────────────────────┘

Overview

The AI Traffic Control API is a distributed, microservices-based system designed to provide real-time traffic signal control recommendations using trained Reinforcement Learning (RL) models.

🗂️ Project Structure

Start here to understand the codebase organization: - Project Structure — Complete directory layout and file descriptions

📚 Conceptual Understanding

Build foundational knowledge about the system design:

  1. High-Level Overview — Bird's-eye view of the architecture
  2. System Components — Key services and their responsibilities
  3. Request-Response Flow — How requests move through the system

🔄 Data & Processing

Understand how data flows and is processed:

  1. Data Flow Through System — Complete data journey from input to output
  2. Detailed Internal Flow - Action Prediction — Deep dive into prediction logic
  3. Model Loading & Caching Strategy — How models are initialized and cached

🔗 Workflows & Protocols

Learn about complete workflows and inter-service communication:

  1. Complete End-to-End Workflow — Full lifecycle from client request to response
  2. Inter-Service Communication Protocol — How services talk to each other
  3. Error Handling Flow — Exception handling and fallback mechanisms

🚀 Operations & Deployment

Learn how the system runs in production:

  1. Deployment Architecture — Cloud deployment setup and infrastructure
  2. Deployment Patterns — Deployment strategies and best practices
  3. Monitoring & Observability Points — Logging, metrics, and health checks

🎯 Design & Optimization

Understand design decisions and optimization considerations:

  1. Architecture Decision Rationale — Why key decisions were made
  2. Security Architecture — Security mechanisms and JWT implementation
  3. Performance Characteristics — Latency, throughput, and performance metrics
  4. Scalability Considerations — How the system scales and handles load

Quick Navigation

For different audiences: