Add files

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.venv
+__pycache__
+.ipynb_checkpoints
+frontend/node_modules
+frontend/dist
+*.pyc
+*.pyo
+*.pyd
+.DS_Store
+.env
+results/
+logs/

.gitignore

@@ -0,0 +1,37 @@
+# ─────────────────────────────────────────────
+# Python
+# ─────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# ─────────────────────────────────────────────
+# Virtual environments
+# ─────────────────────────────────────────────
+venv/
+.venv/
+env/
+
+# ─────────────────────────────────────────────
+# Project outputs (keep directory structure)
+# ─────────────────────────────────────────────
+models/*.pth
+models/*.npy
+results/logs/*.log
+results/plots/*.png
+results/checkpoints/*.pth
+results/metrics.json
+
+# ─────────────────────────────────────────────
+# IDE / OS
+# ─────────────────────────────────────────────
+.idea/
+.vscode/
+*.DS_Store
+Thumbs.db

Architecture.md

@@ -0,0 +1,77 @@
+# Traffic Control Reinforcement Learning Architecture
+
+This document provides a comprehensive A-Z breakdown of the Reinforcement Learning (RL) architecture implemented in the Traffic Signal Control project. 
+
+The system replaces traditional fixed-timing traffic lights with intelligent, adaptive agents that learn optimal signal switching policies. **It features a full-stack React and FastAPI Web Dashboard** to visualize the intersection in real-time.
+
+---
+
+## 1. High-Level System Flow
+
+The architecture follows the standard Reinforcement Learning MDP (Markov Decision Process) loop:
+
+1. **Observe**: The Agent receives the current **State** (queue lengths for 8 lanes, current light phase) from the Environment.
+2. **Decide**: The Agent selects an **Action** (keep the current phase OR switch to the next phase).
+3. **Act**: The Environment executes the action, simulating traffic flow for a specific duration.
+4. **Learn**: The Environment returns a **Reward** (penalty based on total waiting traffic). The Agent uses this to update its neural network.
+
+---
+
+## 2. The Environment (`TrafficEnvironment`)
+
+The environment is the simulated 8-lane intersection built using the `Gymnasium` API.
+
+### 2.1 State Space (Observation)
+We use a continuous **9-dimensional state vector** to perfectly track Straight/Right (SR) and Left-Turn (L) queues:
+*   `[N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L, current_phase]`
+*   **Absolute Normalization**: Queue lengths are normalized linearly by dividing by `20.0` and clipping to `[0, 1]`. This ensures the neural network correctly perceives absolute traffic volume.
+*   **Phase Representation**: The current phase (0 to 3) is normalized to `phase / 3.0`.
+
+### 2.2 Action Space & 4-Phase Cycle
+The agent has a discrete action space of size 2 (Keep or Switch). It cycles through **4 Directional Phases** to completely eliminate turning collisions:
+*   `Phase 0`: North Green (Straight + Left)
+*   `Phase 1`: East Green (Straight + Left)
+*   `Phase 2`: South Green (Straight + Left)
+*   `Phase 3`: West Green (Straight + Left)
+
+### 2.3 Reward Function
+*   **Calculation**: `reward = -(Total Queue Length) / 20.0`
+*   **Clipping**: The reward is hard-clipped to `[-1.0, 1.0]`. 
+*   **Sensitivity**: Dividing by 20.0 ensures the agent receives strong gradient signals even in low-density traffic conditions, forcing it to actively clear small queues.
+
+---
+
+## 3. Traffic Generation (`TrafficGenerator`)
+
+*   **Realistic Volume**: The traffic density is tuned to produce roughly 2,000–4,000 total arrivals per episode.
+*   **Left-Turn Probabilities**: Roughly 20% of generated traffic is routed into the dedicated Left-Turn queues.
+*   **Stochastic Bursts**: There is a 15% probability that a sudden "burst" of traffic will arrive in a random lane, testing the agent's adaptability.
+
+---
+
+## 4. The Deep Q-Network Agent (`DQNAgent`)
+
+A modern Deep RL approach utilizing PyTorch.
+*   **Neural Network Architecture**: 
+    `Input Layer (9)` -> `Hidden Layer (256, ReLU)` -> `Hidden Layer (256, ReLU)` -> `Output Layer (2, Keep/Switch)`
+*   **Experience Replay Buffer**: Transitions `(s, a, r, s', done)` are stored in a circular buffer (size: 50,000). The network trains by sampling random mini-batches (size 256).
+*   **Target Network**: Uses an Online and Target network synced every 10 episodes to stabilize training.
+*   **Hardware Acceleration**: Automatically utilizes CUDA (NVIDIA GPUs) for accelerated tensor operations.
+
+---
+
+## 5. Web Dashboard Architecture
+
+The project features a beautiful full-stack simulation dashboard.
+
+### 5.1 Backend (`backend/app.py`)
+*   Built with **FastAPI**.
+*   Loads the fully trained `dqn_best.pth` model into memory.
+*   Exposes `/api/reset` and `/api/step` endpoints.
+*   When the frontend calls `/api/step`, the backend asks the DQN agent for an action, steps the Python Gymnasium environment, and returns the 9D State and reward back to the UI.
+
+### 5.2 Frontend (`frontend/src/App.jsx`)
+*   Built with **React and Vite**.
+*   **Ultra-Premium Aesthetics**: Features a dark glassmorphism UI, a glowing neon background, and etched asphalt road textures.
+*   **Live Telemetry**: Tracks total throughput and RL reward signals in real-time.
+*   **CSS Animations**: Cars are dynamically rendered in all 8 lanes and visually animate driving straight or turning left (-90deg rotation) when their specific directional light turns green.

Dockerfile

@@ -0,0 +1,33 @@
+# --- Frontend Build Stage ---
+FROM node:20-slim AS frontend-builder
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN npm install
+COPY frontend/ ./
+RUN npm run build
+
+# --- Final Image Stage ---
+FROM python:3.10-slim
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application
+COPY . .
+
+# Copy the built frontend from the builder stage
+COPY --from=frontend-builder /app/frontend/dist ./frontend/dist
+
+# Expose port 7860 (Hugging Face default)
+EXPOSE 7860
+
+# Command to run the application
+# We run from the backend directory to ensure app:app pathing is correct
+CMD ["python", "backend/app.py"]

README copy.md

@@ -0,0 +1,84 @@
+# RL Traffic Signal Control
+
+An advanced Reinforcement Learning implementation for adaptive traffic signal control, featuring a **9-Dimensional Deep Q-Network (DQN)** and an **Ultra-Premium Full-Stack React Dashboard**.
+
+---
+
+## Features
+
+1. **8-Lane Intersection Simulation**: Handles Straight/Right and dedicated Left-Turn queues for North, East, South, and West directions.
+2. **4-Phase Directional System**: Eliminates turning collisions by dedicating phases (North-Only, East-Only, etc.).
+3. **Deep Q-Network**: A PyTorch-based RL agent that dynamically switches lights to keep traffic queues at absolute minimums.
+4. **Full-Stack Dashboard**: A FastAPI backend serves the RL model to a stunning Vite+React frontend featuring live telemetry and CSS vehicle animations.
+
+---
+
+## Quick Start (Web Dashboard)
+
+To view the simulation visually, you need to run the Backend and the Frontend simultaneously.
+
+### 1. Start the FastAPI Backend
+Open a terminal and run:
+```bash
+cd "Traffic Control/backend"
+..\.venv\Scripts\python -m uvicorn app:app --reload
+```
+
+### 2. Start the React Frontend
+Open a **second** terminal and run:
+```bash
+cd "Traffic Control/frontend"
+npm run dev
+```
+
+Open your browser to `http://localhost:5173`, hit **Play**, and watch the DQN manage the intersection in real-time!
+
+---
+
+## Command Line Training Pipeline
+
+If you want to completely retrain the Deep Q-Network from scratch:
+
+```bash
+# 1. Activate virtual environment
+venv\Scripts\activate
+
+# 2. Run the full automated training pipeline
+python main.py --auto
+```
+
+This will run 150 episodes, utilizing CUDA GPU acceleration if available, and automatically save the best performing model to `models/dqn_best.pth`.
+
+---
+
+## Project Structure
+
+```
+Traffic Control/
+├── frontend/                  # React + Vite Web Dashboard
+│   ├── src/App.jsx            # Premium Dashboard UI
+│   └── src/App.css            # Neon Glassmorphism Styles
+├── backend/
+│   └── app.py                 # FastAPI Server mapping RL to HTTP
+├── agent/
+│   └── dqn_agent.py           # Deep Q-Network (PyTorch + GPU)
+├── environment/
+│   ├── traffic_env.py         # Gymnasium environment (9D State)
+│   └── traffic_generator.py   # Stochastic traffic generator
+├── models/                    # Saved agent models (.pth)
+├── results/                   # Logs, metrics, and plots
+├── config.py                  # Neural network & simulation parameters
+└── main.py                    # Training entry point
+```
+
+---
+
+## How It Works (RL Mechanics)
+
+### The Environment
+- **State**: `[N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L, current_phase]` (9 features, absolutely normalized to 0.0-1.0)
+- **Actions**: `0` = keep current phase · `1` = switch to next directional phase
+- **Reward**: `−total_queue / 20.0`, clipped to `[−1, 1]`
+
+### The Model
+A multi-layer perceptron `Input(9) → Linear(256) → ReLU → Linear(256) → ReLU → Linear(2)` trained with experience replay (50,000-transition buffer) and target-network updates. The model aggressively seeks to clear queues to maximize its reward score.

agent/__init__.py

@@ -0,0 +1,21 @@
+"""
+Agent package.
+
+Provides:
+  BaseAgent        — abstract interface
+  QLearningAgent   — tabular Q-learning (NumPy only)
+  DQNAgent         — Deep Q-Network (PyTorch, GPU-accelerated)
+"""
+
+from .base_agent import BaseAgent
+from .q_learning_agent import QLearningAgent
+
+# DQN requires PyTorch
+try:
+    from .dqn_agent import DQNAgent
+    DQN_AVAILABLE = True
+except ImportError:
+    DQN_AVAILABLE = False
+    DQNAgent = None  # type: ignore
+
+__all__ = ["BaseAgent", "QLearningAgent", "DQNAgent"]

agent/base_agent.py

@@ -0,0 +1,61 @@
+"""
+BaseAgent — abstract interface that all RL agents must implement.
+
+Every concrete agent (Q-Learning, DQN, …) must override:
+  • select_action(state, training) → int
+  • train_step(state, action, reward, next_state, done) → float | None
+  • save(filepath)
+  • load(filepath)
+
+Optional hooks:
+  • update_target_network()  – used by DQN
+  • reset()                  – called between episodes if needed
+"""
+
+from abc import ABC, abstractmethod
+
+try:
+    import torch
+    _TORCH_AVAILABLE = True
+except ImportError:
+    _TORCH_AVAILABLE = False
+
+
+class BaseAgent(ABC):
+    """Abstract base class for RL agents."""
+
+    def __init__(self, state_size: int, action_size: int, config: dict):
+        self.state_size = state_size
+        self.action_size = action_size
+        self.config = config
+
+        if _TORCH_AVAILABLE:
+            import torch
+            self.device = torch.device(
+                "cuda" if torch.cuda.is_available() else "cpu"
+            )
+        else:
+            self.device = None
+
+    @abstractmethod
+    def select_action(self, state, training: bool = True) -> int:
+        """Return an action integer for the given state."""
+
+    @abstractmethod
+    def train_step(self, state, action, reward, next_state, done):
+        """Perform one update step; return loss (or None if not applicable)."""
+
+    @abstractmethod
+    def save(self, filepath: str):
+        """Persist the agent to *filepath*."""
+
+    @abstractmethod
+    def load(self, filepath: str):
+        """Restore the agent from *filepath*."""
+
+    # Optional hooks
+    def update_target_network(self):
+        """Sync target network (DQN only)."""
+
+    def reset(self):
+        """Reset any per-episode internal state."""

agent/dqn_agent.py

@@ -0,0 +1,218 @@
+"""
+Deep Q-Network (DQN) Agent — PyTorch implementation with GPU support.
+
+Architecture:
+  Input(5) → Linear(128) → ReLU → Linear(128) → ReLU → Linear(2)
+
+Training improvements (from PROJECT_EXPLANATION.md):
+  • Experience replay buffer (50 000 transitions) breaks temporal correlations.
+  • Target network updated every 10 episodes for stable targets.
+  • Low learning rate (0.0001) prevents oscillation.
+  • Slow epsilon decay (0.998/step) for thorough exploration.
+
+Key results:
+  • Mean reward: −922.41  (0.1% better than fixed signal)
+"""
+
+import random
+from collections import deque
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.optim as optim
+
+from .base_agent import BaseAgent
+
+# ── Device detection ──────────────────────────────────────────────────────────
+DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+print(f"[DQN] Using device: {DEVICE}")
+if torch.cuda.is_available():
+    print(f"[DQN] GPU: {torch.cuda.get_device_name(0)}")
+
+
+# ── Neural network ────────────────────────────────────────────────────────────
+
+class QNetwork(nn.Module):
+    """Fully-connected Q-value approximator."""
+
+    def __init__(self, state_size: int, action_size: int, hidden_layers: list):
+        super().__init__()
+        layers = []
+        in_size = state_size
+        for h in hidden_layers:
+            layers += [nn.Linear(in_size, h), nn.ReLU()]
+            in_size = h
+        layers.append(nn.Linear(in_size, action_size))
+        self.net = nn.Sequential(*layers)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.net(x)
+
+
+# ── Replay buffer ─────────────────────────────────────────────────────────────
+
+class ReplayBuffer:
+    """Fixed-capacity circular experience replay buffer."""
+
+    def __init__(self, capacity: int):
+        self.buffer: deque = deque(maxlen=capacity)
+
+    def push(self, state, action, reward, next_state, done):
+        self.buffer.append((state, action, reward, next_state, done))
+
+    def sample(self, batch_size: int):
+        batch = random.sample(self.buffer, batch_size)
+        states, actions, rewards, next_states, dones = zip(*batch)
+        return states, actions, rewards, next_states, dones
+
+    def __len__(self) -> int:
+        return len(self.buffer)
+
+
+# ── DQN Agent ─────────────────────────────────────────────────────────────────
+
+class DQNAgent(BaseAgent):
+    """
+    DQN with experience replay, target network, and ε-greedy exploration.
+    Automatically uses GPU if available (CUDA).
+    """
+
+    def __init__(self, state_size: int, action_size: int, config: dict):
+        super().__init__(state_size, action_size, config)
+
+        # Hyperparameters
+        self.learning_rate = config["learning_rate"]
+        self.gamma = config["gamma"]
+        self.epsilon = config["epsilon_start"]
+        self.epsilon_end = config["epsilon_end"]
+        self.epsilon_decay = config["epsilon_decay"]
+        self.batch_size = config["batch_size"]
+        self.target_update_freq = config["target_update"]  # episodes
+
+        hidden = config["hidden_layers"]
+
+        # Networks
+        self.q_net = QNetwork(state_size, action_size, hidden).to(DEVICE)
+        self.target_net = QNetwork(state_size, action_size, hidden).to(DEVICE)
+        self.target_net.load_state_dict(self.q_net.state_dict())
+        self.target_net.eval()
+
+        self.optimizer = optim.Adam(self.q_net.parameters(), lr=self.learning_rate)
+        self.criterion = nn.MSELoss()
+        self.memory = ReplayBuffer(config["memory_size"])
+
+        # Train every N environment steps (reduces CPU-GPU round-trip overhead)
+        self.train_frequency = config.get("train_frequency", 4)
+        self._step_counter = 0   # counts env steps since last gradient update
+
+        # Stats
+        self.steps = 0
+        self.episodes = 0
+
+        print(f"[DQN] Initialised  state={state_size}  actions={action_size}  "
+              f"hidden={hidden}  device={DEVICE}  "
+              f"train_every={self.train_frequency}_steps  batch={self.batch_size}")
+
+    # ------------------------------------------------------------------
+    # BaseAgent interface
+    # ------------------------------------------------------------------
+
+    def select_action(self, state, training: bool = True) -> int:
+        """ε-greedy action selection."""
+        if not isinstance(state, np.ndarray):
+            state = np.array(state, dtype=np.float32)
+        if state.dtype != np.float32:
+            state = state.astype(np.float32)
+
+        if training and random.random() < self.epsilon:
+            return random.randrange(self.action_size)
+
+        self.q_net.eval()
+        with torch.no_grad():
+            t = torch.FloatTensor(state).unsqueeze(0).to(DEVICE)
+            action = int(self.q_net(t).argmax().item())
+        self.q_net.train()
+        return action
+
+    def train_step(self, state, action, reward, next_state, done):
+        """
+        Store transition; run a gradient update every `train_frequency` steps.
+
+        Skipping gradient updates on most steps eliminates repeated CPU-GPU
+        data transfers for tiny batches — the dominant latency for small networks.
+
+        Returns:
+            loss (float) if a gradient step was taken, else None.
+        """
+        self.memory.push(state, int(action), float(reward), next_state, bool(done))
+        self._step_counter += 1
+
+        # Only train every N steps
+        if self._step_counter % self.train_frequency != 0:
+            return None
+
+        if len(self.memory) < self.batch_size:
+            return None
+
+        # Sample mini-batch
+        states, actions, rewards, next_states, dones = self.memory.sample(
+            self.batch_size
+        )
+
+        states_t     = torch.FloatTensor(np.array(states)).to(DEVICE)
+        actions_t    = torch.LongTensor(actions).to(DEVICE)
+        rewards_t    = torch.FloatTensor(rewards).to(DEVICE)
+        next_states_t = torch.FloatTensor(np.array(next_states)).to(DEVICE)
+        dones_t      = torch.FloatTensor([float(d) for d in dones]).to(DEVICE)
+
+        # Current Q-values
+        current_q = (
+            self.q_net(states_t)
+            .gather(1, actions_t.unsqueeze(1))
+            .squeeze(1)
+        )
+
+        # Target Q-values (Bellman)
+        with torch.no_grad():
+            next_q   = self.target_net(next_states_t).max(1)[0]
+            target_q = rewards_t + (1.0 - dones_t) * self.gamma * next_q
+
+        loss = self.criterion(current_q, target_q)
+        self.optimizer.zero_grad()
+        loss.backward()
+        self.optimizer.step()
+
+        # Decay epsilon once per gradient step
+        self.epsilon = max(self.epsilon_end, self.epsilon * self.epsilon_decay)
+        self.steps += 1
+
+        return float(loss.item())
+
+    def update_target_network(self):
+        """Copy online-network weights into target network."""
+        self.target_net.load_state_dict(self.q_net.state_dict())
+
+    def save(self, filepath: str):
+        torch.save(
+            {
+                "q_net": self.q_net.state_dict(),
+                "target_net": self.target_net.state_dict(),
+                "optimizer": self.optimizer.state_dict(),
+                "epsilon": self.epsilon,
+                "steps": self.steps,
+                "episodes": self.episodes,
+            },
+            filepath,
+        )
+        print(f"[DQN] Model saved -> {filepath}")
+
+    def load(self, filepath: str):
+        ckpt = torch.load(filepath, map_location=DEVICE)
+        self.q_net.load_state_dict(ckpt["q_net"])
+        self.target_net.load_state_dict(ckpt["target_net"])
+        self.optimizer.load_state_dict(ckpt["optimizer"])
+        self.epsilon = ckpt["epsilon"]
+        self.steps = ckpt["steps"]
+        self.episodes = ckpt["episodes"]
+        print(f"[DQN] Model loaded <- {filepath}  (episodes={self.episodes})")

agent/q_learning_agent.py

@@ -0,0 +1,177 @@
+"""
+Tabular Q-Learning Agent.
+
+Implements Q(s,a) ← Q(s,a) + α [r + γ·max_a' Q(s',a') − Q(s,a)]
+
+Because Q-learning requires a finite state space, the continuous
+observation is discretised into equal-width bins per dimension.
+
+Key results from PROJECT_EXPLANATION.md:
+  • Mean reward: −916.97  (best among all methods)
+  • 5-feature state + 10 bins per dimension performs well
+  • Epsilon-greedy exploration with decay 0.995/episode
+"""
+
+import numpy as np
+from .base_agent import BaseAgent
+
+
+class QLearningAgent(BaseAgent):
+    """
+    Tabular Q-Learning with adaptive state discretisation.
+
+    The Q-table is stored as a sparse dictionary
+    {(discrete_state_tuple, action): q_value} for memory efficiency.
+    """
+
+    def __init__(self, state_size: int, action_size: int, config: dict):
+        super().__init__(state_size, action_size, config)
+
+        # Hyperparameters
+        self.learning_rate = config.get("learning_rate", 0.1)
+        self.gamma = config.get("gamma", 0.99)
+        self.epsilon = config.get("epsilon_start", 1.0)
+        self.epsilon_end = config.get("epsilon_end", 0.01)
+        self.epsilon_decay = config.get("epsilon_decay", 0.995)
+        self.num_bins = config.get("num_bins", 10)
+
+        # Adaptive bounds for normalisation
+        self.state_mins = np.zeros(state_size, dtype=np.float32)
+        self.state_maxs = np.ones(state_size, dtype=np.float32)
+
+        # Sparse Q-table
+        self.q_table: dict = {}
+
+        # Stats
+        self.steps = 0
+        self.episodes = 0
+
+        print(f"[Q-Learning] Initialised  state={state_size}  "
+              f"actions={action_size}  bins={self.num_bins}  "
+              f"lr={self.learning_rate}  gamma={self.gamma}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _discretise(self, state: np.ndarray) -> tuple:
+        """Convert continuous state → discrete tuple (hashable dict key)."""
+        if not isinstance(state, np.ndarray):
+            state = np.array(state, dtype=np.float32)
+        if state.dtype != np.float32:
+            state = state.astype(np.float32)
+
+        # Update running bounds
+        self.state_mins = np.minimum(self.state_mins, state)
+        self.state_maxs = np.maximum(self.state_maxs, state)
+        ranges = np.maximum(self.state_maxs - self.state_mins, 1e-8)
+
+        normalised = np.clip((state - self.state_mins) / ranges, 0.0, 1.0)
+        indices = (normalised * (self.num_bins - 1)).astype(np.int32)
+        return tuple(indices)
+
+    def _get_q(self, discrete_state: tuple, action: int) -> float:
+        return self.q_table.get((discrete_state, action), 0.0)
+
+    def _set_q(self, discrete_state: tuple, action: int, value: float):
+        self.q_table[(discrete_state, action)] = float(value)
+
+    # ------------------------------------------------------------------
+    # BaseAgent interface
+    # ------------------------------------------------------------------
+
+    def select_action(self, state, training: bool = True) -> int:
+        """Epsilon-greedy action selection."""
+        ds = self._discretise(state)
+
+        if training and np.random.random() < self.epsilon:
+            return int(np.random.randint(0, self.action_size))
+
+        q_values = [self._get_q(ds, a) for a in range(self.action_size)]
+        max_q = max(q_values)
+        best = [a for a, q in enumerate(q_values) if q == max_q]
+        return int(np.random.choice(best))
+
+    def train_step(self, state, action, reward, next_state, done):
+        """
+        One Bellman update.
+
+        Returns:
+            td_error (float): Temporal-difference error for this update.
+        """
+        ds = self._discretise(state)
+        dns = self._discretise(next_state)
+
+        action = int(action)
+        reward = float(reward)
+        done = bool(done)
+
+        current_q = self._get_q(ds, action)
+
+        if done:
+            target_q = reward
+        else:
+            next_qs = [self._get_q(dns, a) for a in range(self.action_size)]
+            target_q = reward + self.gamma * max(next_qs)
+
+        td_error = target_q - current_q
+        self._set_q(ds, action, current_q + self.learning_rate * td_error)
+
+        if done:
+            self.epsilon = max(self.epsilon_end, self.epsilon * self.epsilon_decay)
+            self.episodes += 1
+
+        self.steps += 1
+        return float(td_error)
+
+    def save(self, filepath: str):
+        """Serialise Q-table to a .npy file."""
+        payload = {
+            "q_table": dict(self.q_table),
+            "state_mins": self.state_mins.tolist(),
+            "state_maxs": self.state_maxs.tolist(),
+            "epsilon": self.epsilon,
+            "steps": self.steps,
+            "episodes": self.episodes,
+            "num_bins": self.num_bins,
+        }
+        np.save(filepath, payload, allow_pickle=True)
+        print(f"[Q-Learning] Saved Q-table ({len(self.q_table)} entries) -> {filepath}")
+
+    def load(self, filepath: str):
+        """Deserialise Q-table from a .npy file."""
+        payload = np.load(filepath, allow_pickle=True).item()
+        self.q_table = payload["q_table"]
+        self.state_mins = np.array(payload["state_mins"], dtype=np.float32)
+        self.state_maxs = np.array(payload["state_maxs"], dtype=np.float32)
+        self.epsilon = payload["epsilon"]
+        self.steps = payload["steps"]
+        self.episodes = payload["episodes"]
+        self.num_bins = payload["num_bins"]
+        print(f"[Q-Learning] Loaded Q-table ({len(self.q_table)} entries) <- {filepath}")
+
+    # ------------------------------------------------------------------
+    # Diagnostics
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict:
+        if not self.q_table:
+            return {"entries": 0, "unique_states": 0}
+        states = {s for s, _ in self.q_table}
+        vals = list(self.q_table.values())
+        return {
+            "entries": len(self.q_table),
+            "unique_states": len(states),
+            "mean_q": float(np.mean(vals)),
+            "max_q": float(np.max(vals)),
+            "min_q": float(np.min(vals)),
+            "epsilon": round(self.epsilon, 4),
+            "episodes": self.episodes,
+        }
+
+    def __repr__(self):
+        s = self.stats()
+        return (
+            f"QLearningAgent(state={self.state_size}, actions={self.action_size}, "
+            f"bins={self.num_bins}, entries={s['entries']}, ε={s['epsilon']})"
+        )

backend/app.py

@@ -0,0 +1,131 @@
+import sys
+import os
+from pathlib import Path
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+# Add parent directory to path so we can import the RL modules
+ROOT_DIR = Path(__file__).parent.parent
+sys.path.append(str(ROOT_DIR))
+
+import config as cfg
+from environment import TrafficEnvironment
+
+# We will try to load DQN since it performed best
+try:
+    from agent import DQNAgent
+    DQN_AVAILABLE = True
+except ImportError:
+    DQN_AVAILABLE = False
+
+app = FastAPI(title="Traffic RL Simulation API")
+
+# Allow CORS for frontend
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Serve static files from the frontend/dist directory
+# This must be after the API routes for correct routing, but we can define it here 
+# if we mount it at the end. Actually, better to define it after all routes.
+
+# Global instances
+env = TrafficEnvironment(cfg)
+agent = None
+
+# Try to load DQN agent
+if DQN_AVAILABLE:
+    agent = DQNAgent(cfg.STATE_SIZE, cfg.ACTION_SIZE, cfg.DQN_CONFIG)
+    model_path = ROOT_DIR / "models" / "dqn_best.pth"
+    if model_path.exists():
+        agent.load(str(model_path))
+        print("Backend: Loaded DQN Model successfully.")
+    else:
+        print("Backend: DQN Model file not found, using untrained agent.")
+else:
+    # Fallback to QLearning
+    from agent import QLearningAgent
+    agent = QLearningAgent(cfg.STATE_SIZE, cfg.ACTION_SIZE, cfg.Q_LEARNING_CONFIG)
+    model_path = ROOT_DIR / "models" / "q_learning_best.pth"
+    if model_path.exists():
+        agent.load(str(model_path))
+        print("Backend: Loaded Q-Learning Model successfully.")
+    else:
+        print("Backend: Q-Learning Model file not found.")
+
+class StateResponse(BaseModel):
+    queues: list[float]
+    phase: int
+    reward: float
+    vehicles_passed: int
+    step: int
+    total_reward: float
+    is_done: bool
+
+current_state, _ = env.reset()
+total_reward = 0.0
+
+@app.post("/api/reset", response_model=StateResponse)
+def reset_env():
+    global current_state, total_reward
+    current_state, _ = env.reset()
+    total_reward = 0.0
+    return {
+        "queues": env.queue_lengths.tolist(),
+        "phase": env.current_phase,
+        "reward": 0.0,
+        "vehicles_passed": env.vehicles_passed,
+        "step": env.current_step,
+        "total_reward": total_reward,
+        "is_done": False
+    }
+
+@app.post("/api/step", response_model=StateResponse)
+def step_env():
+    global current_state, total_reward
+    
+    # Get action from the loaded agent (evaluation mode)
+    action = agent.select_action(current_state, training=False)
+    
+    # Step the environment
+    next_state, reward, terminated, truncated, info = env.step(action)
+    done = terminated or truncated
+    
+    current_state = next_state
+    total_reward += reward
+    
+    response = {
+        "queues": env.queue_lengths.tolist(),
+        "phase": env.current_phase,
+        "reward": reward,
+        "vehicles_passed": env.vehicles_passed,
+        "step": env.current_step,
+        "total_reward": total_reward,
+        "is_done": done
+    }
+    
+    if done:
+        # Reset for next call if done
+        current_state, _ = env.reset()
+        total_reward = 0.0
+        
+    return response
+
+# Mount the static files at the root
+# Note: Ensure this is the last route defined
+frontend_path = ROOT_DIR / "frontend" / "dist"
+if frontend_path.exists():
+    app.mount("/", StaticFiles(directory=str(frontend_path), html=True), name="static")
+
+if __name__ == "__main__":
+    import uvicorn
+    # Use port 7860 for Hugging Face Spaces compatibility
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run("app:app", host="0.0.0.0", port=port, reload=False)
+    # Restart to load fixed working 9D model

config.py

@@ -0,0 +1,123 @@
+"""
+Configuration file for RL Traffic Signal Control project.
+
+Contains all hyperparameters and settings for the environment,
+agents, and training process.
+"""
+
+import os
+from pathlib import Path
+
+# ============================================================================
+# PROJECT PATHS
+# ============================================================================
+
+ROOT_DIR = Path(__file__).parent
+MODELS_DIR = ROOT_DIR / "models"
+MODELS_DIR.mkdir(exist_ok=True)
+RESULTS_DIR = ROOT_DIR / "results"
+RESULTS_DIR.mkdir(exist_ok=True)
+
+# ============================================================================
+# ENVIRONMENT CONFIGURATION
+# ============================================================================
+
+NUM_LANES = 2                      # Lanes per direction at each intersection
+EPISODE_LENGTH = 3600              # Steps per episode (simulated 1 hour)
+TIME_STEP = 1                      # Simulation time step in seconds
+
+# Traffic generation
+TRAFFIC_DENSITY = 0.02             # Drastically reduced to hit ~1000-5000 throughput per episode
+PEAK_HOURS = [(7, 9), (17, 19)]   # Morning and evening rush hours
+PEAK_MULTIPLIER = 1.5              # Traffic density multiplier during peak hours
+
+# Signal timing constraints
+MIN_GREEN_TIME = 10                # Minimum green light duration (seconds)
+MAX_GREEN_TIME = 60                # Maximum green light duration (seconds)
+YELLOW_TIME = 3                    # Yellow light duration (seconds)
+ALL_RED_TIME = 2                   # All-red clearance time (seconds)
+
+# ============================================================================
+# AGENT CONFIGURATION
+# ============================================================================
+
+AGENT_TYPE = "dqn"                 # Options: "dqn", "q_learning"
+STATE_SIZE = 9                     # [N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L, phase]
+ACTION_SIZE = 2                    # 0=keep current phase, 1=switch phase
+
+# Deep Q-Network (DQN) hyperparameters
+DQN_CONFIG = {
+    "learning_rate": 0.0001,       # Low LR for stability
+    "gamma": 0.99,                 # Discount factor
+    "epsilon_start": 1.0,          # Initial exploration rate
+    "epsilon_end": 0.01,           # Final exploration rate
+    "epsilon_decay": 0.998,        # Slow decay for thorough exploration
+    "memory_size": 50000,          # Replay buffer size
+    "batch_size": 256,             # Larger batch = better GPU utilisation
+    "target_update": 10,           # Target network update frequency (episodes)
+    "hidden_layers": [256, 256],   # Slightly larger network for 9D state space
+    "train_frequency": 4,          # Train every N env steps (reduces CPU-GPU overhead)
+}
+
+# Q-Learning (tabular) hyperparameters
+Q_LEARNING_CONFIG = {
+    "learning_rate": 0.1,          # Alpha
+    "gamma": 0.99,                 # Discount factor
+    "epsilon_start": 1.0,          # Initial exploration rate
+    "epsilon_end": 0.01,           # Final exploration rate
+    "epsilon_decay": 0.995,        # Exploration decay rate
+    "num_bins": 10,                # Bins per state dimension for discretization
+}
+
+# ============================================================================
+# TRAINING CONFIGURATION
+# ============================================================================
+
+NUM_EPISODES = 1000                # Total training episodes
+EVAL_FREQUENCY = 50                # Evaluate every N episodes
+SAVE_FREQUENCY = 100               # Save checkpoint every N episodes
+EARLY_STOPPING_PATIENCE = 100      # Stop if no improvement for N episodes
+MIN_REWARD_THRESHOLD = -1000       # Minimum average reward threshold
+
+# Logging
+LOG_FREQUENCY = 10                 # Log metrics every N episodes
+USE_TENSORBOARD = False            # Disabled by default (no extra deps)
+
+# ============================================================================
+# EVALUATION CONFIGURATION
+# ============================================================================
+
+NUM_EVAL_EPISODES = 10             # Episodes for evaluation
+RENDER_EVAL = False                # Render environment during evaluation
+
+# ============================================================================
+# VISUALIZATION
+# ============================================================================
+
+FIGURE_SIZE = (12, 6)
+DPI = 100
+
+METRICS = [
+    "episode_reward",
+    "average_waiting_time",
+    "average_queue_length",
+    "throughput",
+]
+
+# ============================================================================
+# RANDOM SEED
+# ============================================================================
+
+RANDOM_SEED = 42
+
+# ============================================================================
+# DEVICE
+# ============================================================================
+
+try:
+    import torch
+    DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"[Config] Device: {DEVICE}")
+except ImportError:
+    DEVICE = "cpu"
+    print("[Config] PyTorch not found, using CPU")

environment/__init__.py

@@ -0,0 +1,8 @@
+"""
+Environment package — exposes TrafficEnvironment and TrafficGenerator.
+"""
+
+from .traffic_env import TrafficEnvironment
+from .traffic_generator import TrafficGenerator
+
+__all__ = ["TrafficEnvironment", "TrafficGenerator"]

environment/traffic_env.py

@@ -0,0 +1,246 @@
+"""
+Traffic Environment — Gymnasium-compatible RL environment for traffic signal control.
+
+State space  : [N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L, current_phase]  (9 features, float32 ∈ [0,1])
+Action space : Discrete(2)  →  0 = keep phase,  1 = switch to next phase
+Reward       : −total_queue / 1000,  clipped to [−1, 1]
+
+Key design decisions (from PROJECT_EXPLANATION.md):
+  • Dynamic normalization (divide by current max) prevents state saturation.
+  • Directional phases (N, E, S, W) eliminate turning collisions.
+  • Extended green time (10 steps) when switching makes actions impactful.
+  • Reward clipping prevents gradient explosion during DQN training.
+"""
+
+import numpy as np
+import gymnasium as gym
+from gymnasium import spaces
+
+from .traffic_generator import TrafficGenerator
+
+
+class TrafficEnvironment(gym.Env):
+    """
+    Single-intersection traffic signal control environment.
+
+    The agent controls a 4-phase signal and must minimise total vehicle
+    waiting time across all four approach lanes (N / E / S / W).
+    """
+
+    metadata = {"render_modes": ["human"], "render_fps": 30}
+
+    # Phase → green queue indices mapping (8 queues total)
+    # Phase 0: North (0=SR, 1=L), Phase 1: East (2=SR, 3=L)
+    # Phase 2: South (4=SR, 5=L), Phase 3: West (6=SR, 7=L)
+    _PHASE_GREEN: dict = {
+        0: [0, 1],
+        1: [2, 3],
+        2: [4, 5],
+        3: [6, 7],
+    }
+
+    def __init__(self, config=None):
+        """
+        Args:
+            config: Configuration module/object. Uses default config if None.
+        """
+        super().__init__()
+
+        if config is None:
+            import config as default_config
+            config = default_config
+
+        self.config = config
+
+        # Environment parameters
+        self.num_lanes = config.NUM_LANES
+        self.episode_length = config.EPISODE_LENGTH
+        self.min_green_time = 8            # Steps before a switch is allowed
+        self.extended_green_time = 10      # Extra processing steps after switch
+        self.yellow_time = config.YELLOW_TIME
+
+        # Traffic simulator
+        self.traffic_generator = TrafficGenerator(config)
+
+        # ── Observation space ──────────────────────────────────────────
+        # 8 queues + phase, all normalised ∈ [0, 1]
+        self.observation_space = spaces.Box(
+            low=0.0, high=1.0, shape=(9,), dtype=np.float32
+        )
+
+        # ── Action space ───────────────────────────────────────────────
+        # 0 = keep current phase  |  1 = switch to next phase
+        self.action_space = spaces.Discrete(2)
+
+        # Internal state
+        self.current_step: int = 0
+        self.current_phase: int = 0
+        self.time_in_phase: int = 0
+        self.queue_lengths: np.ndarray = np.zeros(8, dtype=np.float32)
+        self.waiting_times: np.ndarray = np.zeros(8, dtype=np.float32)
+        self.vehicles_passed: int = 0
+        self.last_action: int = 0
+
+        self.render_mode = None
+
+    # ------------------------------------------------------------------
+    # Gymnasium API
+    # ------------------------------------------------------------------
+
+    def reset(self, seed=None, options=None):
+        """Reset environment to initial state and return (observation, info)."""
+        super().reset(seed=seed)
+
+        self.current_step = 0
+        self.current_phase = 0
+        self.time_in_phase = 0
+        self.queue_lengths = np.zeros(8, dtype=np.float32)
+        self.waiting_times = np.zeros(8, dtype=np.float32)
+        self.vehicles_passed = 0
+        self.last_action = 0
+
+        self.traffic_generator.reset()
+
+        observation = self._get_observation()
+        info = self._get_info()
+
+        return observation, info
+
+    def step(self, action: int):
+        """
+        Execute one decision step.
+
+        Args:
+            action: 0 = keep current phase,  1 = switch to next phase.
+
+        Returns:
+            (observation, reward, terminated, truncated, info)
+        """
+        if not self.action_space.contains(action):
+            raise ValueError(f"Invalid action {action!r}. Must be 0 or 1.")
+
+        is_switching = bool(action == 1)
+
+        # ── Phase switch ───────────────────────────────────────────────
+        if is_switching and self.time_in_phase >= self.min_green_time:
+            self.current_phase = (self.current_phase + 1) % 4
+            self.time_in_phase = 0
+
+            # Extended green: process multiple clearing steps for visible impact
+            for _ in range(self.extended_green_time):
+                cleared = self._process_phase()
+                self.vehicles_passed += int(cleared)
+
+        self.time_in_phase += 1
+        self.current_step += 1
+
+        # ── Vehicle arrivals ───────────────────────────────────────────
+        new_vehicles = self.traffic_generator.generate(self.current_step)
+        self.queue_lengths = self.queue_lengths + new_vehicles
+
+        # ── Normal phase processing ────────────────────────────────────
+        vehicles_passing = self._process_phase()
+        self.vehicles_passed += int(vehicles_passing)
+
+        # ── Waiting time accumulation ──────────────────────────────────
+        self.waiting_times = self.waiting_times + self.queue_lengths
+
+        # ── Reward ────────────────────────────────────────────────────
+        reward = float(self._calculate_reward())
+
+        self.last_action = action
+
+        terminated = bool(self.current_step >= self.episode_length)
+        truncated = False
+
+        observation = self._get_observation()
+        info = self._get_info()
+        info["waiting_time"] = float(np.sum(self.waiting_times))
+        info["queue_length"] = float(np.sum(self.queue_lengths))
+
+        return observation, reward, terminated, truncated, info
+
+    def render(self):
+        """Console render (human mode)."""
+        if self.render_mode == "human":
+            print(
+                f"Step: {self.current_step:4d} | Phase: {self.current_phase} | "
+                f"Queues: {self.queue_lengths} | Passed: {self.vehicles_passed}"
+            )
+
+    def close(self):
+        pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_observation(self) -> np.ndarray:
+        """
+        Build the 9-dimensional state vector.
+
+        Queue features are normalised by the current maximum queue value
+        (dynamic normalisation) to preserve relative lane differences and
+        prevent saturation when absolute queue counts are large.
+        """
+        queue_state = self.queue_lengths.copy().astype(np.float32)
+
+        # Absolute normalisation (cap at 20 vehicles to keep ∈ [0, 1])
+        queue_state = np.clip(queue_state / 20.0, 0.0, 1.0)
+
+        phase_state = np.array(
+            [float(self.current_phase) / 3.0], dtype=np.float32
+        )
+
+        observation = np.concatenate([queue_state, phase_state])
+
+        # Validate
+        assert observation.shape == (9,), f"Bad obs shape: {observation.shape}"
+        assert observation.dtype == np.float32
+        assert not np.any(np.isnan(observation)), "NaN in observation"
+        assert not np.any(np.isinf(observation)), "Inf in observation"
+
+        return observation
+
+    def _get_info(self) -> dict:
+        return {
+            "current_step": self.current_step,
+            "current_phase": self.current_phase,
+            "total_queue_length": float(np.sum(self.queue_lengths)),
+            "average_waiting_time": float(np.mean(self.waiting_times)),
+            "vehicles_passed": self.vehicles_passed,
+        }
+
+    def _process_phase(self) -> float:
+        """
+        Clear vehicles from green-light lanes.
+
+        Returns:
+            vehicles_passing: Number of vehicles that cleared this step.
+        """
+        green_dirs = self._PHASE_GREEN.get(self.current_phase, [])
+        vehicles_passing = 0.0
+
+        for d in green_dirs:
+            if self.queue_lengths[d] > 0:
+                passing = min(
+                    self.queue_lengths[d],
+                    float(np.random.randint(1, 3)),
+                )
+                self.queue_lengths[d] -= passing
+                vehicles_passing += passing
+
+        return vehicles_passing
+
+    def _calculate_reward(self) -> float:
+        """
+        Compute reward signal.
+
+          reward = −total_queue / 1000   (clipped to [−1, 1])
+
+        Dividing by 1000 keeps the magnitude in a range suitable for
+        stable neural-network training; clipping prevents extreme gradients.
+        """
+        total_queue = float(np.sum(self.queue_lengths))
+        reward = -total_queue / 20.0
+        return float(np.clip(reward, -1.0, 1.0))

environment/traffic_generator.py

@@ -0,0 +1,129 @@
+"""
+Traffic Generator — simulates vehicle arrivals at the intersection.
+
+Implements complex, realistic traffic patterns:
+  - Extreme lane imbalance  (North gets ~70% of traffic)
+  - Dynamic peak/low phases (alternating every 100 steps)
+  - Random traffic bursts   (15% probability, 4× multiplier)
+  - Variable vehicle counts (2–8 per arrival event)
+"""
+
+import numpy as np
+
+
+class TrafficGenerator:
+    """
+    Generates stochastic traffic patterns for the simulation.
+
+    The deliberately uneven distribution ensures that a fixed-timing signal
+    cannot match the performance of an adaptive RL agent.
+    """
+
+    def __init__(self, config):
+        """
+        Args:
+            config: Module or object exposing traffic-related constants.
+        """
+        self.config = config
+
+        # Base density — drastically lowered for ~2000-4000 throughput
+        self.traffic_density = config.TRAFFIC_DENSITY
+
+        self.peak_hours = config.PEAK_HOURS
+        self.peak_multiplier = config.PEAK_MULTIPLIER
+
+        # Random number generator
+        self.rng = np.random.default_rng()
+
+        # Burst parameters
+        self.burst_probability = 0.15       # 15% chance of burst per step
+        self.burst_active = False
+        self.burst_duration = 0
+        self.burst_direction = 0
+
+        # Lane imbalance: North gets ~45% of traffic — uneven but manageable
+        # Previously [2.8, 0.4, 0.5, 0.3] caused North density > 1.0 every step
+        weights = np.array([1.8, 0.7, 0.7, 0.6])
+        self.lane_weights = weights / weights.sum() * 4  # Normalised
+
+        # Dynamic phase: alternates peak/low every 100 steps
+        self.phase_length = 100
+        self.current_phase_step = 0
+        self.is_peak_phase = True
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def reset(self):
+        """Reset generator state at the start of each episode."""
+        self.burst_active = False
+        self.burst_duration = 0
+        self.burst_direction = 0
+        self.current_phase_step = 0
+        self.is_peak_phase = True
+
+    def generate(self, current_step: int) -> np.ndarray:
+        """
+        Generate new vehicles for the current time step.
+
+        Args:
+            current_step: Current simulation step counter.
+
+        Returns:
+            new_vehicles: Array [N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L] of vehicle counts.
+        """
+        # --- Dynamic phase (peak / low, toggles every 100 steps) ---
+        self.current_phase_step += 1
+        if self.current_phase_step >= self.phase_length:
+            self.current_phase_step = 0
+            self.is_peak_phase = not self.is_peak_phase
+
+        density = (
+            self.traffic_density * 1.5
+            if self.is_peak_phase
+            else self.traffic_density * 0.5
+        )
+
+        # Traditional peak-hour multiplier
+        hour = (current_step // 3600) % 24
+        for start_h, end_h in self.peak_hours:
+            if start_h <= hour < end_h:
+                density *= self.peak_multiplier
+                break
+
+        # --- Traffic burst ---
+        if not self.burst_active:
+            if self.rng.random() < self.burst_probability:
+                self.burst_active = True
+                self.burst_duration = int(self.rng.integers(15, 40))
+                self.burst_direction = int(self.rng.integers(0, 4))
+        else:
+            self.burst_duration -= 1
+            if self.burst_duration <= 0:
+                self.burst_active = False
+
+        # --- Vehicle arrivals per direction (8 queues) ---
+        new_vehicles = np.zeros(8, dtype=np.float32)
+        for direction in range(4):
+            lane_density = density * self.lane_weights[direction]
+
+            if self.burst_active and direction == self.burst_direction:
+                lane_density *= 4.0            # Burst spike
+                
+            if self.rng.random() < lane_density:
+                # 1-3 vehicles arrive
+                total_arriving = self.rng.integers(1, 4)
+                for _ in range(total_arriving):
+                    # 20% chance of turning left
+                    is_left_turn = self.rng.random() < 0.2
+                    if is_left_turn:
+                        new_vehicles[direction * 2 + 1] += 1.0  # Left turn queue
+                    else:
+                        new_vehicles[direction * 2] += 1.0      # Straight/Right queue
+
+        return new_vehicles
+
+    def set_density(self, density: float):
+        """Override base traffic density (0.0–1.0)."""
+        self.traffic_density = float(np.clip(density, 0.0, 1.0))

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

frontend/package-lock.json

@@ -0,0 +1,962 @@
+{
+  "name": "frontend",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "frontend",
+      "version": "0.0.0",
+      "dependencies": {
+        "lucide-react": "^1.11.0",
+        "react": "^19.2.5",
+        "react-dom": "^19.2.5"
+      },
+      "devDependencies": {
+        "@vitejs/plugin-react": "^6.0.1",
+        "typescript": "~6.0.2",
+        "vite": "^8.0.10"
+      }
+    },
+    "node_modules/@emnapi/core": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
+      "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.2.1",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+      "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
+      "integrity": "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tybys/wasm-util": "^0.10.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "peerDependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1"
+      }
+    },
+    "node_modules/@oxc-project/types": {
+      "version": "0.127.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz",
+      "integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/Boshen"
+      }
+    },
+    "node_modules/@rolldown/binding-android-arm64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-arm64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-x64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-freebsd-x64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz",
+      "integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-gnu": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-musl": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz",
+      "integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-s390x-gnu": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-gnu": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz",
+      "integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-musl": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz",
+      "integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-openharmony-arm64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-wasm32-wasi": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz",
+      "integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "1.10.0",
+        "@emnapi/runtime": "1.10.0",
+        "@napi-rs/wasm-runtime": "^1.1.4"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-arm64-msvc": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz",
+      "integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-x64-msvc": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz",
+      "integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
+      "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+      "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.0.1.tgz",
+      "integrity": "sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rolldown/pluginutils": "1.0.0-rc.7"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0",
+        "babel-plugin-react-compiler": "^1.0.0",
+        "vite": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@rolldown/plugin-babel": {
+          "optional": true
+        },
+        "babel-plugin-react-compiler": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitejs/plugin-react/node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.7",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.7.tgz",
+      "integrity": "sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/lightningcss": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
+      "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "detect-libc": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      },
+      "optionalDependencies": {
+        "lightningcss-android-arm64": "1.32.0",
+        "lightningcss-darwin-arm64": "1.32.0",
+        "lightningcss-darwin-x64": "1.32.0",
+        "lightningcss-freebsd-x64": "1.32.0",
+        "lightningcss-linux-arm-gnueabihf": "1.32.0",
+        "lightningcss-linux-arm64-gnu": "1.32.0",
+        "lightningcss-linux-arm64-musl": "1.32.0",
+        "lightningcss-linux-x64-gnu": "1.32.0",
+        "lightningcss-linux-x64-musl": "1.32.0",
+        "lightningcss-win32-arm64-msvc": "1.32.0",
+        "lightningcss-win32-x64-msvc": "1.32.0"
+      }
+    },
+    "node_modules/lightningcss-android-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+      "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
+      "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+      "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-freebsd-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+      "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm-gnueabihf": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+      "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+      "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+      "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+      "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+      "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-arm64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+      "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-x64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+      "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lucide-react": {
+      "version": "1.11.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.11.0.tgz",
+      "integrity": "sha512-UOhjdztXCgdBReRcIhsvz2siIBogfv/lhJEIViCpLt924dO+GDms9T7DNoucI23s6kEPpe988m5N0D2ajnzb2g==",
+      "license": "ISC",
+      "peerDependencies": {
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.12",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
+      "integrity": "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.5",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.5.tgz",
+      "integrity": "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.2.5",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.5.tgz",
+      "integrity": "sha512-J5bAZz+DXMMwW/wV3xzKke59Af6CHY7G4uYLN1OvBcKEsWOs4pQExj86BBKamxl/Ik5bx9whOrvBlSDfWzgSag==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.5"
+      }
+    },
+    "node_modules/rolldown": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
+      "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@oxc-project/types": "=0.127.0",
+        "@rolldown/pluginutils": "1.0.0-rc.17"
+      },
+      "bin": {
+        "rolldown": "bin/cli.mjs"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "optionalDependencies": {
+        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "license": "MIT"
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/typescript": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/vite": {
+      "version": "8.0.10",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
+      "integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "lightningcss": "^1.32.0",
+        "picomatch": "^4.0.4",
+        "postcss": "^8.5.10",
+        "rolldown": "1.0.0-rc.17",
+        "tinyglobby": "^0.2.16"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "@vitejs/devtools": "^0.1.0",
+        "esbuild": "^0.27.0 || ^0.28.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "@vitejs/devtools": {
+          "optional": true
+        },
+        "esbuild": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

frontend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.10"
+  },
+  "dependencies": {
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  }
+}

frontend/src/App.css

@@ -0,0 +1,200 @@
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600;700;800&display=swap');
+
+:root {
+  --bg-gradient: linear-gradient(135deg, #09090b 0%, #1e1b4b 100%);
+  --glass-bg: rgba(15, 23, 42, 0.4);
+  --glass-border: rgba(255, 255, 255, 0.08);
+  --neon-blue: #38bdf8;
+  --neon-blue-glow: rgba(56, 189, 248, 0.6);
+  --neon-pink: #f472b6;
+  --neon-pink-glow: rgba(244, 114, 182, 0.6);
+  --neon-purple: #c084fc;
+  --neon-purple-glow: rgba(192, 132, 252, 0.6);
+  --neon-green: #34d399;
+  --neon-green-glow: rgba(52, 211, 153, 0.6);
+  --asphalt: #18181b;
+  --line-color: rgba(255,255,255,0.15);
+  --stop-line: #cbd5e1;
+}
+
+body {
+  margin: 0; padding: 0;
+  font-family: 'Outfit', sans-serif;
+  background: var(--bg-gradient);
+  color: white;
+  min-height: 100vh;
+  overflow-x: hidden;
+}
+
+* { box-sizing: border-box; }
+
+/* Moving background blobs */
+.bg-blob { position: fixed; border-radius: 50%; filter: blur(100px); z-index: -1; opacity: 0.4; animation: float 10s infinite alternate; }
+.blob-1 { width: 400px; height: 400px; background: rgba(56, 189, 248, 0.2); top: 10%; left: 10%; }
+.blob-2 { width: 500px; height: 500px; background: rgba(192, 132, 252, 0.15); bottom: 10%; right: 10%; }
+.blob-3 { width: 300px; height: 300px; background: rgba(52, 211, 153, 0.15); bottom: 50%; left: 40%; animation-delay: -5s; }
+
+@keyframes float { 100% { transform: translateY(50px) translateX(50px); } }
+
+/* Layout */
+.app-container { max-width: 1400px; margin: 0 auto; padding: 2rem; }
+
+.premium-header {
+  display: flex; justify-content: space-between; align-items: center; margin-bottom: 2rem;
+  padding: 1.5rem 2rem; background: var(--glass-bg); border: 1px solid var(--glass-border);
+  border-radius: 16px; backdrop-filter: blur(20px);
+}
+.header-brand { display: flex; align-items: center; gap: 1rem; }
+.icon-wrapper { background: rgba(56,189,248,0.1); color: var(--neon-blue); padding: 12px; border-radius: 12px; border: 1px solid rgba(56,189,248,0.2); }
+.header-brand h1 { margin: 0; font-size: 1.5rem; font-weight: 800; letter-spacing: 1px; }
+.header-brand p { margin: 0; color: #94a3b8; font-size: 0.875rem; font-weight: 300; }
+
+.header-status { display: flex; align-items: center; gap: 0.75rem; background: rgba(0,0,0,0.3); padding: 0.5rem 1.25rem; border-radius: 999px; border: 1px solid var(--glass-border); font-size: 0.875rem; font-weight: 600; letter-spacing: 1px; }
+.pulse-dot { width: 8px; height: 8px; background: var(--neon-green); border-radius: 50%; box-shadow: 0 0 10px var(--neon-green); animation: pulse 2s infinite; }
+@keyframes pulse { 0% { opacity: 1; } 50% { opacity: 0.3; } 100% { opacity: 1; } }
+
+.main-layout { display: grid; grid-template-columns: 1fr 380px; gap: 2rem; }
+
+/* INTERSECTION CENTERPIECE */
+.intersection-wrapper {
+  position: relative; border-radius: 24px; padding: 2rem; display: flex; flex-direction: column; align-items: center;
+  background: rgba(0,0,0,0.2); border: 1px solid var(--glass-border); box-shadow: 0 25px 50px -12px rgba(0,0,0,0.5);
+  overflow: hidden;
+}
+
+.intersection-container {
+  position: relative; width: 600px; height: 600px; background: #000; border-radius: 20px;
+  box-shadow: inset 0 0 50px rgba(0,0,0,0.8); overflow: hidden; margin-bottom: 2rem;
+}
+
+.road { position: absolute; background: var(--asphalt); }
+.road-vertical { width: 160px; height: 100%; left: 50%; transform: translateX(-50%); border-left: 2px solid var(--line-color); border-right: 2px solid var(--line-color); }
+.road-horizontal { width: 100%; height: 160px; top: 50%; transform: translateY(-50%); border-top: 2px solid var(--line-color); border-bottom: 2px solid var(--line-color); }
+
+.lane-divider { position: absolute; }
+.vertical-left, .vertical-right { width: 2px; height: 100%; background: var(--line-color); background-image: linear-gradient(to bottom, var(--line-color) 50%, transparent 50%); background-size: 100% 30px; }
+.vertical-left { left: 53px; }
+.vertical-right { left: 106px; }
+
+.horizontal-top, .horizontal-bottom { width: 100%; height: 2px; background: var(--line-color); background-image: linear-gradient(to right, var(--line-color) 50%, transparent 50%); background-size: 30px 100%; }
+.horizontal-top { top: 53px; }
+.horizontal-bottom { top: 106px; }
+
+.stop-line { position: absolute; background: var(--stop-line); }
+.sl-top { width: 160px; height: 4px; top: 220px; }
+.sl-bottom { width: 160px; height: 4px; bottom: 220px; }
+.sl-left { height: 160px; width: 4px; left: 220px; }
+.sl-right { height: 160px; width: 4px; right: 220px; }
+
+.intersection-center {
+  position: absolute; width: 160px; height: 160px; background: var(--asphalt);
+  left: 50%; top: 50%; transform: translate(-50%, -50%); z-index: 2;
+  display: flex; align-items: center; justify-content: center;
+}
+.center-logo {
+  width: 80px; height: 80px; border-radius: 50%; border: 2px dashed rgba(255,255,255,0.05); display: flex; align-items: center; justify-content: center;
+}
+
+/* Premium Traffic Lights */
+.traffic-fixture {
+  position: absolute; display: flex; background: #27272a; padding: 8px; border-radius: 12px;
+  gap: 8px; z-index: 10; border: 2px solid #3f3f46; box-shadow: 0 10px 20px rgba(0,0,0,0.5), inset 0 2px 5px rgba(255,255,255,0.1);
+}
+.t-light { width: 16px; height: 16px; border-radius: 50%; background: #000; box-shadow: inset 0 2px 4px rgba(0,0,0,0.8); transition: all 0.3s; }
+.t-light.red.active { background: #ef4444; box-shadow: 0 0 20px #ef4444, inset 0 0 5px #fff; }
+.t-light.green.active { background: #10b981; box-shadow: 0 0 20px #10b981, inset 0 0 5px #fff; }
+
+.tf-north { flex-direction: column; top: 120px; left: 140px; }
+.tf-south { flex-direction: column; bottom: 120px; right: 140px; }
+.tf-east { top: 140px; right: 120px; }
+.tf-west { bottom: 140px; left: 120px; }
+
+/* Vehicles */
+.queue { position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 5; pointer-events: none; }
+.car { position: absolute; border-radius: 6px; display: flex; justify-content: center; align-items: center; }
+.car-glow { width: 100%; height: 100%; border-radius: inherit; }
+
+.car-n { width: 22px; height: 40px; }
+.car-n .car-glow { background: linear-gradient(180deg, var(--neon-blue) 0%, #1e40af 100%); box-shadow: 0 0 15px var(--neon-blue-glow); }
+.car-n.straight { bottom: calc(50% + 80px + (var(--idx) * 45px)); left: calc(50% - 66px); }
+.car-n.left-turn { bottom: calc(50% + 80px + (var(--idx) * 45px)); left: calc(50% - 14px); }
+
+.car-s { width: 22px; height: 40px; }
+.car-s .car-glow { background: linear-gradient(0deg, var(--neon-pink) 0%, #9d174d 100%); box-shadow: 0 0 15px var(--neon-pink-glow); }
+.car-s.straight { top: calc(50% + 80px + (var(--idx) * 45px)); left: calc(50% + 44px); }
+.car-s.left-turn { top: calc(50% + 80px + (var(--idx) * 45px)); left: calc(50% - 8px); }
+
+.car-e { width: 40px; height: 22px; }
+.car-e .car-glow { background: linear-gradient(270deg, var(--neon-purple) 0%, #5b21b6 100%); box-shadow: 0 0 15px var(--neon-purple-glow); }
+.car-e.straight { left: calc(50% + 80px + (var(--idx) * 45px)); top: calc(50% - 66px); }
+.car-e.left-turn { left: calc(50% + 80px + (var(--idx) * 45px)); top: calc(50% - 14px); }
+
+.car-w { width: 40px; height: 22px; }
+.car-w .car-glow { background: linear-gradient(90deg, var(--neon-green) 0%, #065f46 100%); box-shadow: 0 0 15px var(--neon-green-glow); }
+.car-w.straight { right: calc(50% + 80px + (var(--idx) * 45px)); top: calc(50% + 44px); }
+.car-w.left-turn { right: calc(50% + 80px + (var(--idx) * 45px)); top: calc(50% - 8px); }
+
+/* Animations */
+@keyframes pSV { to { transform: translateY(300px); opacity: 0; } }
+@keyframes pSVU { to { transform: translateY(-300px); opacity: 0; } }
+@keyframes pSH { to { transform: translateX(-300px); opacity: 0; } }
+@keyframes pSHR { to { transform: translateX(300px); opacity: 0; } }
+@keyframes tLN { to { transform: translate(150px, 150px) rotate(-90deg); opacity: 0; } }
+@keyframes tLS { to { transform: translate(-150px, -150px) rotate(-90deg); opacity: 0; } }
+@keyframes tLE { to { transform: translate(-150px, 150px) rotate(-90deg); opacity: 0; } }
+@keyframes tLW { to { transform: translate(150px, -150px) rotate(-90deg); opacity: 0; } }
+
+.car-n.straight.animating { animation: pSV 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-n.left-turn.animating { animation: tLN 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-s.straight.animating { animation: pSVU 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-s.left-turn.animating { animation: tLS 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-e.straight.animating { animation: pSH 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-e.left-turn.animating { animation: tLE 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-w.straight.animating { animation: pSHR 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+.car-w.left-turn.animating { animation: tLW 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; }
+
+/* Control Bar */
+.premium-controls {
+  display: flex; gap: 1rem; background: rgba(0,0,0,0.4); padding: 1rem 2rem; border-radius: 999px;
+  border: 1px solid var(--glass-border); box-shadow: 0 10px 30px rgba(0,0,0,0.5); backdrop-filter: blur(10px);
+}
+.p-btn {
+  display: flex; align-items: center; gap: 0.5rem; padding: 0.75rem 1.5rem; border: none; border-radius: 999px;
+  font-weight: 700; cursor: pointer; transition: all 0.2s; font-family: 'Outfit', sans-serif; letter-spacing: 1px;
+}
+.btn-play { background: var(--neon-blue); color: #000; box-shadow: 0 0 15px var(--neon-blue-glow); }
+.btn-play:hover { transform: translateY(-2px); box-shadow: 0 0 25px var(--neon-blue-glow); }
+.btn-pause { background: var(--neon-pink); color: #000; box-shadow: 0 0 15px var(--neon-pink-glow); }
+.btn-ghost { background: transparent; color: white; border: 1px solid rgba(255,255,255,0.2); }
+.btn-ghost:hover:not(:disabled) { background: rgba(255,255,255,0.1); }
+.btn-ghost:disabled { opacity: 0.3; cursor: not-allowed; }
+.control-divider { width: 1px; background: rgba(255,255,255,0.1); margin: 0 0.5rem; }
+.p-select { background: transparent; color: white; border: none; outline: none; font-family: 'Outfit'; font-weight: 600; cursor: pointer; }
+.p-select option { background: #18181b; }
+
+/* Sidebar Metrics */
+.metrics-sidebar { display: flex; flex-direction: column; gap: 1.5rem; }
+.glass-card { background: var(--glass-bg); backdrop-filter: blur(20px); border: 1px solid var(--glass-border); border-radius: 20px; padding: 1.5rem; }
+.glass-card h3 { margin: 0 0 1rem 0; font-size: 0.875rem; text-transform: uppercase; letter-spacing: 2px; color: #94a3b8; }
+
+.primary-card { background: linear-gradient(135deg, rgba(56, 189, 248, 0.1) 0%, rgba(15, 23, 42, 0.4) 100%); border: 1px solid rgba(56,189,248,0.3); }
+.big-metric { display: flex; flex-direction: column; margin-bottom: 1rem; }
+.big-metric .value { font-size: 3.5rem; font-weight: 800; line-height: 1; color: var(--neon-blue); text-shadow: 0 0 20px var(--neon-blue-glow); }
+.big-metric .label { font-size: 0.875rem; color: #cbd5e1; margin-top: 0.5rem; font-weight: 300; }
+
+.mini-progress { width: 100%; height: 4px; background: rgba(0,0,0,0.3); border-radius: 2px; overflow: hidden; margin-bottom: 0.5rem; }
+.mini-progress .fill { height: 100%; background: var(--neon-blue); box-shadow: 0 0 10px var(--neon-blue); transition: width 0.3s; }
+.step-count { font-size: 0.75rem; color: #64748b; font-weight: 600; }
+
+.reward-value { font-size: 2.5rem; font-weight: 800; }
+.reward-value.positive { color: var(--neon-green); text-shadow: 0 0 15px var(--neon-green-glow); }
+.reward-value.negative { color: var(--neon-pink); text-shadow: 0 0 15px var(--neon-pink-glow); }
+.reward-desc { font-size: 0.875rem; color: #94a3b8; margin: 0.5rem 0 0 0; line-height: 1.4; }
+
+.telemetry-grid { display: flex; flex-direction: column; gap: 0.75rem; }
+.t-item { background: rgba(0,0,0,0.2); border: 1px solid rgba(255,255,255,0.05); padding: 1rem; border-radius: 12px; display: flex; justify-content: space-between; align-items: center; transition: all 0.3s; }
+.t-item.active-lane { background: rgba(52, 211, 153, 0.1); border-color: rgba(52, 211, 153, 0.3); box-shadow: 0 0 20px rgba(52, 211, 153, 0.1); }
+.t-head { font-weight: 700; letter-spacing: 1px; color: #cbd5e1; }
+.t-item.active-lane .t-head { color: var(--neon-green); }
+.t-data { font-family: monospace; font-size: 1.1rem; }
+.t-data span { color: #475569; margin: 0 0.5rem; }

frontend/src/App.jsx

@@ -0,0 +1,230 @@
+import { useState, useEffect } from 'react';
+import { Play, Pause, RotateCcw, FastForward, Activity, MapPin } from 'lucide-react';
+import './App.css';
+
+const API_BASE = window.location.origin === 'http://localhost:5173' || window.location.origin === 'http://127.0.0.1:5173'
+  ? 'http://127.0.0.1:8000/api' 
+  : '/api';
+
+
+function App() {
+  const [state, setState] = useState({
+    queues: [0, 0, 0, 0, 0, 0, 0, 0], // N_SR, N_L, E_SR, E_L, S_SR, S_L, W_SR, W_L
+    phase: 0,
+    reward: 0,
+    vehicles_passed: 0,
+    step: 0,
+    total_reward: 0,
+    is_done: false
+  });
+  
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [speedMs, setSpeedMs] = useState(250);
+  
+  const fetchState = async (endpoint) => {
+    try {
+      const res = await fetch(`${API_BASE}/${endpoint}`, { method: 'POST' });
+      const data = await res.json();
+      setState(data);
+      if (data.is_done) {
+        setIsPlaying(false);
+      }
+    } catch (err) {
+      console.error(err);
+      setIsPlaying(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchState('reset');
+  }, []);
+
+  useEffect(() => {
+    let interval;
+    if (isPlaying) {
+      interval = setInterval(() => {
+        fetchState('step');
+      }, speedMs);
+    }
+    return () => clearInterval(interval);
+  }, [isPlaying, speedMs]);
+
+  // Phase logic: 0=N, 1=E, 2=S, 3=W
+  const isNGreen = state.phase === 0;
+  const isEGreen = state.phase === 1;
+  const isSGreen = state.phase === 2;
+  const isWGreen = state.phase === 3;
+
+  const renderCars = (count, direction, isLeftTurn) => {
+    const displayCount = Math.min(count, 5); // Cap visuals for ultra-premium look
+    return Array.from({ length: displayCount }).map((_, i) => (
+      <div 
+        key={i} 
+        className={`car car-${direction} ${isLeftTurn ? 'left-turn' : 'straight'} ${i === 0 && ((direction==='n'&&isNGreen)||(direction==='e'&&isEGreen)||(direction==='s'&&isSGreen)||(direction==='w'&&isWGreen)) && isPlaying ? 'animating' : ''}`} 
+        style={{ '--idx': i }}
+      >
+        <div className="car-glow"></div>
+      </div>
+    ));
+  };
+
+  const getPhaseName = () => {
+    if (isNGreen) return "NORTH GREEN";
+    if (isEGreen) return "EAST GREEN";
+    if (isSGreen) return "SOUTH GREEN";
+    if (isWGreen) return "WEST GREEN";
+  };
+
+  return (
+    <>
+      <div className="bg-blob blob-1"></div>
+      <div className="bg-blob blob-2"></div>
+      <div className="bg-blob blob-3"></div>
+
+      <div className="app-container">
+        <header className="premium-header">
+          <div className="header-brand">
+            <div className="icon-wrapper">
+              <Activity size={28} />
+            </div>
+            <div>
+              <h1>Nexus Control</h1>
+              <p>Deep Q-Network Traffic Simulation</p>
+            </div>
+          </div>
+          <div className="header-status">
+            <div className="pulse-dot"></div>
+            <span>System Active • {getPhaseName()}</span>
+          </div>
+        </header>
+
+        <main className="main-layout">
+          {/* INTERSECTION CENTERPIECE */}
+          <div className="intersection-wrapper glass-panel">
+            <div className="intersection-container">
+              {/* Roads */}
+              <div className="road road-vertical">
+                <div className="lane-divider vertical-left"></div>
+                <div className="lane-divider vertical-right"></div>
+                <div className="stop-line sl-top"></div>
+                <div className="stop-line sl-bottom"></div>
+              </div>
+              <div className="road road-horizontal">
+                <div className="lane-divider horizontal-top"></div>
+                <div className="lane-divider horizontal-bottom"></div>
+                <div className="stop-line sl-left"></div>
+                <div className="stop-line sl-right"></div>
+              </div>
+              <div className="intersection-center">
+                <div className="center-logo"><MapPin size={24} opacity={0.2} /></div>
+              </div>
+
+              {/* Traffic Light Fixtures */}
+              <div className="traffic-fixture tf-north">
+                <div className={`t-light red ${!isNGreen ? 'active' : ''}`}></div>
+                <div className={`t-light green ${isNGreen ? 'active' : ''}`}></div>
+              </div>
+              <div className="traffic-fixture tf-east">
+                <div className={`t-light red ${!isEGreen ? 'active' : ''}`}></div>
+                <div className={`t-light green ${isEGreen ? 'active' : ''}`}></div>
+              </div>
+              <div className="traffic-fixture tf-south">
+                <div className={`t-light red ${!isSGreen ? 'active' : ''}`}></div>
+                <div className={`t-light green ${isSGreen ? 'active' : ''}`}></div>
+              </div>
+              <div className="traffic-fixture tf-west">
+                <div className={`t-light red ${!isWGreen ? 'active' : ''}`}></div>
+                <div className={`t-light green ${isWGreen ? 'active' : ''}`}></div>
+              </div>
+
+              {/* Vehicles */}
+              <div className="queue q-north">
+                {renderCars(state.queues[0], 'n', false)}
+                {renderCars(state.queues[1], 'n', true)}
+              </div>
+              <div className="queue q-east">
+                {renderCars(state.queues[2], 'e', false)}
+                {renderCars(state.queues[3], 'e', true)}
+              </div>
+              <div className="queue q-south">
+                {renderCars(state.queues[4], 's', false)}
+                {renderCars(state.queues[5], 's', true)}
+              </div>
+              <div className="queue q-west">
+                {renderCars(state.queues[6], 'w', false)}
+                {renderCars(state.queues[7], 'w', true)}
+              </div>
+            </div>
+            
+            {/* Control Bar Overlay */}
+            <div className="premium-controls">
+              <button onClick={() => setIsPlaying(!isPlaying)} className={`p-btn ${isPlaying ? 'btn-pause' : 'btn-play'}`}>
+                {isPlaying ? <><Pause size={20}/> PAUSE</> : <><Play size={20}/> START</>}
+              </button>
+              <div className="control-divider"></div>
+              <button onClick={() => fetchState('step')} disabled={isPlaying} className="p-btn btn-ghost">
+                <FastForward size={18}/> STEP
+              </button>
+              <button onClick={() => fetchState('reset')} className="p-btn btn-ghost">
+                <RotateCcw size={18}/> RESET
+              </button>
+              <div className="control-divider"></div>
+              <select value={speedMs} onChange={(e) => setSpeedMs(Number(e.target.value))} className="p-select">
+                <option value={500}>0.5x Speed</option>
+                <option value={250}>1.0x Speed</option>
+                <option value={100}>2.0x Speed</option>
+              </select>
+            </div>
+          </div>
+
+          {/* METRICS SIDEBAR */}
+          <aside className="metrics-sidebar">
+            <div className="glass-card primary-card">
+              <h3>AI Performance</h3>
+              <div className="big-metric">
+                <span className="value">{state.vehicles_passed}</span>
+                <span className="label">Total Vehicles Cleared</span>
+              </div>
+              <div className="mini-progress">
+                <div className="fill" style={{ width: `${(state.step/3600)*100}%` }}></div>
+              </div>
+              <div className="step-count">Time: {state.step} / 3600</div>
+            </div>
+
+            <div className="glass-card">
+              <h3>Reward Signal</h3>
+              <div className={`reward-value ${state.total_reward < -50 ? 'negative' : 'positive'}`}>
+                {state.total_reward.toFixed(2)}
+              </div>
+              <p className="reward-desc">Optimizing to keep queues at absolute minimums.</p>
+            </div>
+
+            <div className="glass-card queues-card">
+              <h3>Live Lane Telemetry</h3>
+              <div className="telemetry-grid">
+                <div className={`t-item ${isNGreen ? 'active-lane' : ''}`}>
+                  <div className="t-head">NORTH</div>
+                  <div className="t-data">SR: {state.queues[0]} <span>|</span> L: {state.queues[1]}</div>
+                </div>
+                <div className={`t-item ${isEGreen ? 'active-lane' : ''}`}>
+                  <div className="t-head">EAST</div>
+                  <div className="t-data">SR: {state.queues[2]} <span>|</span> L: {state.queues[3]}</div>
+                </div>
+                <div className={`t-item ${isSGreen ? 'active-lane' : ''}`}>
+                  <div className="t-head">SOUTH</div>
+                  <div className="t-data">SR: {state.queues[4]} <span>|</span> L: {state.queues[5]}</div>
+                </div>
+                <div className={`t-item ${isWGreen ? 'active-lane' : ''}`}>
+                  <div className="t-head">WEST</div>
+                  <div className="t-data">SR: {state.queues[6]} <span>|</span> L: {state.queues[7]}</div>
+                </div>
+              </div>
+            </div>
+          </aside>
+        </main>
+      </div>
+    </>
+  );
+}
+
+export default App;

frontend/src/counter.ts

@@ -0,0 +1,9 @@
+export function setupCounter(element: HTMLButtonElement) {
+  let counter = 0
+  const setCounter = (count: number) => {
+    counter = count
+    element.innerHTML = `Count is ${counter}`
+  }
+  element.addEventListener('click', () => setCounter(counter + 1))
+  setCounter(0)
+}

frontend/src/index.css

@@ -0,0 +1 @@
+/* Cleared to use App.css */

frontend/src/main.jsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('app')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

frontend/src/main.ts

@@ -0,0 +1,60 @@
+import './style.css'
+import typescriptLogo from './assets/typescript.svg'
+import viteLogo from './assets/vite.svg'
+import heroImg from './assets/hero.png'
+import { setupCounter } from './counter.ts'
+
+document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
+<section id="center">
+  <div class="hero">
+    <img src="${heroImg}" class="base" width="170" height="179">
+    <img src="${typescriptLogo}" class="framework" alt="TypeScript logo"/>
+    <img src="${viteLogo}" class="vite" alt="Vite logo" />
+  </div>
+  <div>
+    <h1>Get started</h1>
+    <p>Edit <code>src/main.ts</code> and save to test <code>HMR</code></p>
+  </div>
+  <button id="counter" type="button" class="counter"></button>
+</section>
+
+<div class="ticks"></div>
+
+<section id="next-steps">
+  <div id="docs">
+    <svg class="icon" role="presentation" aria-hidden="true"><use href="/icons.svg#documentation-icon"></use></svg>
+    <h2>Documentation</h2>
+    <p>Your questions, answered</p>
+    <ul>
+      <li>
+        <a href="https://vite.dev/" target="_blank">
+          <img class="logo" src="${viteLogo}" alt="" />
+          Explore Vite
+        </a>
+      </li>
+      <li>
+        <a href="https://www.typescriptlang.org" target="_blank">
+          <img class="button-icon" src="${typescriptLogo}" alt="">
+          Learn more
+        </a>
+      </li>
+    </ul>
+  </div>
+  <div id="social">
+    <svg class="icon" role="presentation" aria-hidden="true"><use href="/icons.svg#social-icon"></use></svg>
+    <h2>Connect with us</h2>
+    <p>Join the Vite community</p>
+    <ul>
+      <li><a href="https://github.com/vitejs/vite" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#github-icon"></use></svg>GitHub</a></li>
+      <li><a href="https://chat.vite.dev/" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#discord-icon"></use></svg>Discord</a></li>
+      <li><a href="https://x.com/vite_js" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#x-icon"></use></svg>X.com</a></li>
+      <li><a href="https://bsky.app/profile/vite.dev" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#bluesky-icon"></use></svg>Bluesky</a></li>
+    </ul>
+  </div>
+</section>
+
+<div class="ticks"></div>
+<section id="spacer"></section>
+`
+
+setupCounter(document.querySelector<HTMLButtonElement>('#counter')!)

frontend/src/style.css

@@ -0,0 +1,296 @@
+:root {
+  --text: #6b6375;
+  --text-h: #08060d;
+  --bg: #fff;
+  --border: #e5e4e7;
+  --code-bg: #f4f3ec;
+  --accent: #aa3bff;
+  --accent-bg: rgba(170, 59, 255, 0.1);
+  --accent-border: rgba(170, 59, 255, 0.5);
+  --social-bg: rgba(244, 243, 236, 0.5);
+  --shadow:
+    rgba(0, 0, 0, 0.1) 0 10px 15px -3px, rgba(0, 0, 0, 0.05) 0 4px 6px -2px;
+
+  --sans: system-ui, 'Segoe UI', Roboto, sans-serif;
+  --heading: system-ui, 'Segoe UI', Roboto, sans-serif;
+  --mono: ui-monospace, Consolas, monospace;
+
+  font: 18px/145% var(--sans);
+  letter-spacing: 0.18px;
+  color-scheme: light dark;
+  color: var(--text);
+  background: var(--bg);
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  @media (max-width: 1024px) {
+    font-size: 16px;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text: #9ca3af;
+    --text-h: #f3f4f6;
+    --bg: #16171d;
+    --border: #2e303a;
+    --code-bg: #1f2028;
+    --accent: #c084fc;
+    --accent-bg: rgba(192, 132, 252, 0.15);
+    --accent-border: rgba(192, 132, 252, 0.5);
+    --social-bg: rgba(47, 48, 58, 0.5);
+    --shadow:
+      rgba(0, 0, 0, 0.4) 0 10px 15px -3px, rgba(0, 0, 0, 0.25) 0 4px 6px -2px;
+  }
+
+  #social .button-icon {
+    filter: invert(1) brightness(2);
+  }
+}
+
+body {
+  margin: 0;
+}
+
+h1,
+h2 {
+  font-family: var(--heading);
+  font-weight: 500;
+  color: var(--text-h);
+}
+
+h1 {
+  font-size: 56px;
+  letter-spacing: -1.68px;
+  margin: 32px 0;
+  @media (max-width: 1024px) {
+    font-size: 36px;
+    margin: 20px 0;
+  }
+}
+h2 {
+  font-size: 24px;
+  line-height: 118%;
+  letter-spacing: -0.24px;
+  margin: 0 0 8px;
+  @media (max-width: 1024px) {
+    font-size: 20px;
+  }
+}
+p {
+  margin: 0;
+}
+
+code,
+.counter {
+  font-family: var(--mono);
+  display: inline-flex;
+  border-radius: 4px;
+  color: var(--text-h);
+}
+
+code {
+  font-size: 15px;
+  line-height: 135%;
+  padding: 4px 8px;
+  background: var(--code-bg);
+}
+
+.counter {
+  font-size: 16px;
+  padding: 5px 10px;
+  border-radius: 5px;
+  color: var(--accent);
+  background: var(--accent-bg);
+  border: 2px solid transparent;
+  transition: border-color 0.3s;
+  margin-bottom: 24px;
+
+  &:hover {
+    border-color: var(--accent-border);
+  }
+  &:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+}
+
+.hero {
+  position: relative;
+
+  .base,
+  .framework,
+  .vite {
+    inset-inline: 0;
+    margin: 0 auto;
+  }
+
+  .base {
+    width: 170px;
+    position: relative;
+    z-index: 0;
+  }
+
+  .framework,
+  .vite {
+    position: absolute;
+  }
+
+  .framework {
+    z-index: 1;
+    top: 34px;
+    height: 28px;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(44deg) rotateY(39deg)
+      scale(1.4);
+  }
+
+  .vite {
+    z-index: 0;
+    top: 107px;
+    height: 26px;
+    width: auto;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(40deg) rotateY(39deg)
+      scale(0.8);
+  }
+}
+
+#app {
+  width: 1126px;
+  max-width: 100%;
+  margin: 0 auto;
+  text-align: center;
+  border-inline: 1px solid var(--border);
+  min-height: 100svh;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+}
+
+#center {
+  display: flex;
+  flex-direction: column;
+  gap: 25px;
+  place-content: center;
+  place-items: center;
+  flex-grow: 1;
+
+  @media (max-width: 1024px) {
+    padding: 32px 20px 24px;
+    gap: 18px;
+  }
+}
+
+#next-steps {
+  display: flex;
+  border-top: 1px solid var(--border);
+  text-align: left;
+
+  & > div {
+    flex: 1 1 0;
+    padding: 32px;
+    @media (max-width: 1024px) {
+      padding: 24px 20px;
+    }
+  }
+
+  .icon {
+    margin-bottom: 16px;
+    width: 22px;
+    height: 22px;
+  }
+
+  @media (max-width: 1024px) {
+    flex-direction: column;
+    text-align: center;
+  }
+}
+
+#docs {
+  border-right: 1px solid var(--border);
+
+  @media (max-width: 1024px) {
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+  }
+}
+
+#next-steps ul {
+  list-style: none;
+  padding: 0;
+  display: flex;
+  gap: 8px;
+  margin: 32px 0 0;
+
+  .logo {
+    height: 18px;
+  }
+
+  a {
+    color: var(--text-h);
+    font-size: 16px;
+    border-radius: 6px;
+    background: var(--social-bg);
+    display: flex;
+    padding: 6px 12px;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    transition: box-shadow 0.3s;
+
+    &:hover {
+      box-shadow: var(--shadow);
+    }
+    .button-icon {
+      height: 18px;
+      width: 18px;
+    }
+  }
+
+  @media (max-width: 1024px) {
+    margin-top: 20px;
+    flex-wrap: wrap;
+    justify-content: center;
+
+    li {
+      flex: 1 1 calc(50% - 8px);
+    }
+
+    a {
+      width: 100%;
+      justify-content: center;
+      box-sizing: border-box;
+    }
+  }
+}
+
+#spacer {
+  height: 88px;
+  border-top: 1px solid var(--border);
+  @media (max-width: 1024px) {
+    height: 48px;
+  }
+}
+
+.ticks {
+  position: relative;
+  width: 100%;
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    top: -4.5px;
+    border: 5px solid transparent;
+  }
+
+  &::before {
+    left: 0;
+    border-left-color: var(--border);
+  }
+  &::after {
+    right: 0;
+    border-right-color: var(--border);
+  }
+}

frontend/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "esnext",
+    "lib": ["ES2023", "DOM"],
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

frontend/vite.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})

main.py

@@ -0,0 +1,374 @@
+"""
+main.py — RL Traffic Signal Control entry point.
+
+Automated pipeline (recommended):
+    python main.py --auto
+
+Manual usage:
+    python main.py --mode train  --agent q_learning --episodes 50
+    python main.py --mode train  --agent dqn        --episodes 150
+    python main.py --mode eval   --agent q_learning --model-path models/q_learning_best.pth
+    python main.py --mode eval   --agent dqn        --model-path models/dqn_best.pth
+    python main.py --mode fixed                     # Fixed-signal baseline only
+
+The --auto flag runs the full pipeline:
+  1. Fixed-signal baseline (10 episodes)
+  2. Q-Learning training   (50 episodes)
+  3. DQN training          (150 episodes)
+  4. Evaluation & comparison plots
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+# ── Project imports ───────────────────────────────────────────────────────────
+import config as cfg
+from environment import TrafficEnvironment
+from agent import QLearningAgent, DQNAgent, DQN_AVAILABLE
+from training import Trainer, Evaluator
+from utils import setup_logger, MetricsTracker, plot_training_curves
+from utils.visualizer import plot_comparison, plot_bar_comparison
+
+logger = setup_logger("main")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Factory helpers
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def make_env() -> TrafficEnvironment:
+    """Create a fresh environment instance."""
+    return TrafficEnvironment(cfg)
+
+
+def make_q_learning_agent() -> QLearningAgent:
+    """Instantiate a Q-Learning agent using project config."""
+    return QLearningAgent(
+        state_size=cfg.STATE_SIZE,
+        action_size=cfg.ACTION_SIZE,
+        config=cfg.Q_LEARNING_CONFIG,
+    )
+
+
+def make_dqn_agent():
+    """Instantiate a DQN agent using project config (requires PyTorch)."""
+    if not DQN_AVAILABLE:
+        logger.error("PyTorch is not installed — DQN unavailable.")
+        logger.error("Install with: pip install torch")
+        sys.exit(1)
+    return DQNAgent(
+        state_size=cfg.STATE_SIZE,
+        action_size=cfg.ACTION_SIZE,
+        config=cfg.DQN_CONFIG,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Fixed-signal baseline
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class FixedSignalAgent:
+    """
+    Round-robin fixed-timing signal — cycles phases every 30 steps.
+    Used as the comparison baseline.
+    """
+
+    def __init__(self, switch_interval: int = 30):
+        self.switch_interval = switch_interval
+        self._step = 0
+
+    def select_action(self, state, training: bool = False) -> int:
+        self._step += 1
+        return 1 if self._step % self.switch_interval == 0 else 0
+
+    def train_step(self, *args, **kwargs):
+        return None
+
+    def save(self, filepath):
+        pass
+
+    def load(self, filepath):
+        pass
+
+    def reset(self):
+        self._step = 0
+
+
+def run_fixed_baseline(num_episodes: int = 10) -> tuple[list[float], dict]:
+    """
+    Evaluate the fixed-timing signal for *num_episodes* episodes.
+
+    Returns:
+        (episode_rewards, summary_dict)
+    """
+    logger.info("=" * 60)
+    logger.info(f"FIXED-SIGNAL BASELINE  ({num_episodes} episodes)")
+    logger.info("=" * 60)
+
+    agent = FixedSignalAgent(switch_interval=30)
+    env = make_env()
+    rewards: list[float] = []
+    info: dict = {}
+
+    for ep in range(1, num_episodes + 1):
+        state, _ = env.reset()
+        agent.reset()
+        ep_reward = 0.0
+        done = False
+
+        while not done:
+            action = agent.select_action(state)
+            state, reward, terminated, truncated, info = env.step(action)
+            done = terminated or truncated
+            ep_reward += reward
+
+        rewards.append(ep_reward)
+        logger.info(f"  Episode {ep:3d}/{num_episodes}  reward={ep_reward:.2f}")
+
+    mean_r = float(np.mean(rewards))
+    logger.info(f"Baseline mean reward: {mean_r:.2f}")
+
+    return rewards, {
+        "mean_reward": mean_r,
+        "std_reward": float(np.std(rewards)),
+        "best_reward": float(np.max(rewards)),
+        "mean_waiting_time": float(info.get("average_waiting_time", 0)),
+        "mean_queue_length": float(info.get("total_queue_length", 0)),
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Training mode
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def run_training(agent_type: str, num_episodes: int):
+    """
+    Train the specified agent and save the best model.
+
+    Args:
+        agent_type:   "q_learning" or "dqn".
+        num_episodes: Number of training episodes.
+    """
+    logger.info("=" * 60)
+    logger.info(f"TRAINING  agent={agent_type}  episodes={num_episodes}")
+    logger.info("=" * 60)
+
+    env = make_env()
+
+    if agent_type == "q_learning":
+        cfg.AGENT_TYPE = "q_learning"
+        agent = make_q_learning_agent()
+    elif agent_type == "dqn":
+        cfg.AGENT_TYPE = "dqn"
+        agent = make_dqn_agent()
+    else:
+        logger.error(f"Unknown agent type: {agent_type!r}")
+        sys.exit(1)
+
+    trainer = Trainer(env, agent, cfg)
+    trainer.train(num_episodes)
+
+    logger.info(f"Training complete. Best reward: {trainer.best_reward:.2f}")
+    return trainer
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Evaluation mode
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def run_evaluation(agent_type: str, model_path: str, num_episodes: int = 10) -> dict:
+    """
+    Load a saved model and evaluate it.
+
+    Args:
+        agent_type:   "q_learning" or "dqn".
+        model_path:   Path to saved model file.
+        num_episodes: Evaluation episodes.
+
+    Returns:
+        Evaluation results dictionary.
+    """
+    logger.info("=" * 60)
+    logger.info(f"EVALUATION  agent={agent_type}  model={model_path}")
+    logger.info("=" * 60)
+
+    env = make_env()
+
+    if agent_type == "q_learning":
+        cfg.AGENT_TYPE = "q_learning"
+        agent = make_q_learning_agent()
+    else:
+        cfg.AGENT_TYPE = "dqn"
+        agent = make_dqn_agent()
+
+    agent.load(model_path)
+    evaluator = Evaluator(env, agent, cfg)
+    results = evaluator.evaluate(num_episodes)
+
+    logger.info("Evaluation results:")
+    for k, v in results.items():
+        logger.info(f"  {k}: {v:.4f}" if isinstance(v, float) else f"  {k}: {v}")
+
+    return results
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Automated pipeline
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def run_auto_pipeline():
+    """
+    Full automated pipeline:
+      1. Fixed-signal baseline
+      2. Q-Learning training (50 episodes)
+      3. DQN training        (150 episodes)
+      4. Evaluation of all methods
+      5. Comparison plots
+    """
+    logger.info("╔" + "═" * 58 + "╗")
+    logger.info("║   AUTOMATED RL TRAFFIC SIGNAL CONTROL PIPELINE          ║")
+    logger.info("╚" + "═" * 58 + "╝")
+
+    summary: dict[str, dict] = {}
+
+    # ── 1. Fixed-signal baseline ──────────────────────────────────────
+    baseline_rewards, baseline_results = run_fixed_baseline(num_episodes=10)
+    summary["Fixed Signal"] = baseline_results
+
+    # ── 2. Q-Learning ────────────────────────────────────────────────
+    ql_trainer = run_training("q_learning", num_episodes=50)
+    summary["Q-Learning"] = {
+        "mean_reward": ql_trainer.metrics.get_mean("episode_reward"),
+        "best_reward": ql_trainer.best_reward,
+        "std_reward":  ql_trainer.metrics.get_std("episode_reward"),
+    }
+
+    # ── 3. DQN ───────────────────────────────────────────────────────
+    if DQN_AVAILABLE:
+        dqn_trainer = run_training("dqn", num_episodes=150)
+        summary["DQN"] = {
+            "mean_reward": dqn_trainer.metrics.get_mean("episode_reward"),
+            "best_reward": dqn_trainer.best_reward,
+            "std_reward":  dqn_trainer.metrics.get_std("episode_reward"),
+        }
+    else:
+        logger.warning("DQN skipped (PyTorch not available).")
+
+    # ── 4. Print comparison table ─────────────────────────────────────
+    _print_comparison_table(summary)
+
+    # ── 5. Plots ──────────────────────────────────────────────────────
+    _generate_comparison_plots(summary)
+
+    logger.info("Pipeline complete.")
+
+
+def _print_comparison_table(summary: dict):
+    """Print a neat comparison table to stdout."""
+    print("\n")
+    print("=" * 60)
+    print(f"{'Method':<18} {'Mean Reward':>14} {'Best Reward':>14}")
+    print("-" * 60)
+    baseline_mean = summary.get("Fixed Signal", {}).get("mean_reward", 0)
+
+    for method, res in summary.items():
+        mean_r = res.get("mean_reward", 0)
+        best_r = res.get("best_reward", 0)
+        delta = mean_r - baseline_mean if method != "Fixed Signal" else 0
+        delta_str = f"  ({delta:+.2f})" if method != "Fixed Signal" else ""
+        print(f"{method:<18} {mean_r:>14.2f} {best_r:>14.2f}{delta_str}")
+
+    print("=" * 60)
+    print()
+
+
+def _generate_comparison_plots(summary: dict):
+    """Save bar-chart comparison of mean rewards."""
+    scores = {m: r.get("mean_reward", 0) for m, r in summary.items()}
+    save_path = cfg.RESULTS_DIR / "plots" / "comparison_bar.png"
+    plot_bar_comparison(
+        scores,
+        title="Mean Reward by Method (higher = better)",
+        ylabel="Mean Reward",
+        save_path=save_path,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CLI
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        description="RL Traffic Signal Control",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python main.py --auto
+  python main.py --mode train  --agent q_learning --episodes 50
+  python main.py --mode train  --agent dqn        --episodes 150
+  python main.py --mode eval   --agent q_learning --model-path models/q_learning_best.pth
+  python main.py --mode fixed
+        """,
+    )
+
+    p.add_argument(
+        "--auto",
+        action="store_true",
+        help="Run the full automated pipeline (recommended)",
+    )
+    p.add_argument(
+        "--mode",
+        choices=["train", "eval", "fixed"],
+        default="train",
+        help="Mode to run (ignored when --auto is set)",
+    )
+    p.add_argument(
+        "--agent",
+        choices=["q_learning", "dqn"],
+        default="q_learning",
+        help="Agent type",
+    )
+    p.add_argument(
+        "--episodes",
+        type=int,
+        default=50,
+        help="Number of episodes",
+    )
+    p.add_argument(
+        "--model-path",
+        type=str,
+        default=None,
+        help="Path to saved model file (required for --mode eval)",
+    )
+
+    return p
+
+
+def main():
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.auto:
+        run_auto_pipeline()
+        return
+
+    if args.mode == "fixed":
+        run_fixed_baseline(num_episodes=args.episodes)
+
+    elif args.mode == "train":
+        run_training(args.agent, args.episodes)
+
+    elif args.mode == "eval":
+        if args.model_path is None:
+            parser.error("--model-path is required for --mode eval")
+        run_evaluation(args.agent, args.model_path, num_episodes=10)
+
+
+if __name__ == "__main__":
+    main()

models/.gitkeep

@@ -0,0 +1 @@
+# Saved model files (.pth for DQN, .npy for Q-Learning) are stored here.

requirements.txt

@@ -0,0 +1,19 @@
+# Core (required)
+numpy>=1.24.0,<2.0.0
+gymnasium>=0.29.0,<1.0.0
+matplotlib>=3.7.0,<4.0.0
+
+# Deep learning — PyTorch (for DQN + GPU support)
+# CPU-only wheels (smaller):
+#   pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+# GPU wheels (CUDA 12.1):
+#   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+torch>=2.0.0
+
+# Optional — progress bars
+tqdm>=4.65.0
+
+# Web (for deployment)
+fastapi>=0.100.0
+uvicorn>=0.23.0
+pydantic>=2.0.0

results/.gitkeep

@@ -0,0 +1 @@
+# Training logs, plots, checkpoints and metrics.json are written here.

test_env.py

@@ -0,0 +1,56 @@
+import sys
+import os
+from pathlib import Path
+
+# Add project root to path
+ROOT_DIR = Path(__file__).parent
+sys.path.append(str(ROOT_DIR))
+
+import config as cfg
+from environment import TrafficEnvironment
+from agent import DQNAgent
+
+def test_model():
+    print("Initializing environment...")
+    env = TrafficEnvironment(cfg)
+    
+    print("Initializing Agent...")
+    agent = DQNAgent(cfg.STATE_SIZE, cfg.ACTION_SIZE, cfg.DQN_CONFIG)
+    
+    model_path = ROOT_DIR / "models" / "dqn_best.pth"
+    if model_path.exists():
+        agent.load(str(model_path))
+        print("Model loaded successfully.")
+    else:
+        print("ERROR: Model not found at", model_path)
+        return
+        
+    state, _ = env.reset()
+    
+    print("\n--- Simulation Test ---")
+    action_1_count = 0
+    phase_changes = 0
+    last_phase = env.current_phase
+    
+    for i in range(200):
+        action = agent.select_action(state, training=False)
+        if action == 1:
+            action_1_count += 1
+            
+        next_state, reward, _, _, info = env.step(action)
+        
+        if env.current_phase != last_phase:
+            phase_changes += 1
+            print(f"Step {i}: Phase changed from {last_phase} to {env.current_phase}")
+            last_phase = env.current_phase
+            
+        state = next_state
+        
+    print("\n--- Test Results ---")
+    print(f"Total Steps: 200")
+    print(f"Agent chose Switch (1): {action_1_count} times")
+    print(f"Actual Phase Changes: {phase_changes}")
+    print(f"Final Queues: {env.queue_lengths}")
+    
+if __name__ == '__main__':
+    test_model()

training/__init__.py

@@ -0,0 +1,8 @@
+"""
+Training package.
+"""
+
+from .trainer import Trainer
+from .evaluator import Evaluator
+
+__all__ = ["Trainer", "Evaluator"]

training/evaluator.py

@@ -0,0 +1,99 @@
+"""
+Evaluator — assesses a trained agent over multiple episodes without exploration.
+
+Produces summary statistics:
+  mean/std reward, mean waiting time, mean queue length, mean throughput.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+try:
+    from tqdm import tqdm as _tqdm
+    _TQDM = True
+except ImportError:
+    _TQDM = False
+
+from utils.logger import setup_logger
+
+
+class Evaluator:
+    """
+    Runs a trained agent in greedy (no exploration) mode.
+
+    Args:
+        env:    Environment instance (reset between episodes).
+        agent:  Trained agent (select_action called with training=False).
+        config: Project config module.
+    """
+
+    def __init__(self, env, agent, config):
+        self.env = env
+        self.agent = agent
+        self.config = config
+        self.logger = setup_logger("evaluator")
+
+    def evaluate(self, num_episodes: int, render: bool = False) -> dict:
+        """
+        Evaluate the agent for *num_episodes* episodes.
+
+        Args:
+            num_episodes: Number of evaluation episodes.
+            render:       Call env.render() at each step if True.
+
+        Returns:
+            Dictionary with mean/std reward and mean performance metrics.
+        """
+        self.logger.info(f"Evaluating for {num_episodes} episodes …")
+
+        rewards, waits, queues, thrus = [], [], [], []
+
+        iterator = (
+            _tqdm(range(num_episodes), desc="Eval", unit="ep")
+            if _TQDM
+            else range(num_episodes)
+        )
+
+        for _ in iterator:
+            ep_reward, info = self._run_episode(render=render)
+            rewards.append(ep_reward)
+            waits.append(info.get("average_waiting_time", 0.0))
+            queues.append(info.get("total_queue_length", 0.0))
+            thrus.append(info.get("vehicles_passed", 0))
+
+        results = {
+            "mean_reward":       float(np.mean(rewards)),
+            "std_reward":        float(np.std(rewards)),
+            "best_reward":       float(np.max(rewards)),
+            "mean_waiting_time": float(np.mean(waits)),
+            "mean_queue_length": float(np.mean(queues)),
+            "mean_throughput":   float(np.mean(thrus)),
+        }
+
+        self.logger.info(f"  mean reward : {results['mean_reward']:.2f}")
+        self.logger.info(f"  best reward : {results['best_reward']:.2f}")
+        self.logger.info(f"  mean wait   : {results['mean_waiting_time']:.2f}")
+
+        return results
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _run_episode(self, render: bool = False) -> tuple[float, dict]:
+        state, _ = self.env.reset()
+        ep_reward = 0.0
+        done = False
+        info: dict = {}
+
+        while not done:
+            action = self.agent.select_action(state, training=False)
+            next_state, reward, terminated, truncated, info = self.env.step(action)
+            done = terminated or truncated
+            if render:
+                self.env.render()
+            state = next_state
+            ep_reward += reward
+
+        return ep_reward, info

training/trainer.py

@@ -0,0 +1,258 @@
+"""
+Trainer — manages the training loop for any BaseAgent.
+
+Features:
+  • Per-episode logging (episode, reward, waiting time, queue, throughput)
+  • Automatic best-model saving
+  • Periodic checkpoints
+  • Early stopping
+  • DQN target-network updates
+  • Graceful error recovery (episode-level try/except)
+  • Optional tqdm progress bar
+"""
+
+from __future__ import annotations
+
+import sys
+import traceback
+from pathlib import Path
+
+import numpy as np
+
+try:
+    from tqdm import tqdm
+    _TQDM = True
+except ImportError:
+    _TQDM = False
+
+from utils.logger import setup_logger
+from utils.metrics import MetricsTracker
+
+
+class Trainer:
+    """
+    Orchestrates the RL training loop.
+
+    Args:
+        env:    A Gymnasium-compatible environment.
+        agent:  Any agent that inherits :class:`BaseAgent`.
+        config: The project config module.
+    """
+
+    def __init__(self, env, agent, config):
+        self.env = env
+        self.agent = agent
+        self.config = config
+
+        # Directories
+        config.RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+        config.MODELS_DIR.mkdir(parents=True, exist_ok=True)
+        (config.RESULTS_DIR / "logs").mkdir(exist_ok=True)
+        (config.RESULTS_DIR / "plots").mkdir(exist_ok=True)
+        (config.RESULTS_DIR / "checkpoints").mkdir(exist_ok=True)
+
+        # Logger
+        log_file = config.RESULTS_DIR / "logs" / "training.log"
+        self.logger = setup_logger("trainer", log_file=str(log_file))
+
+        # Metrics
+        self.metrics = MetricsTracker()
+
+        # State
+        self.best_reward: float = -np.inf
+        self.episodes_without_improvement: int = 0
+        self.current_episode: int = 0
+        self.total_steps: int = 0
+
+        self.logger.info("=" * 70)
+        self.logger.info("TRAINER READY")
+        self.logger.info(f"  Agent type : {config.AGENT_TYPE}")
+        self.logger.info(f"  Results dir: {config.RESULTS_DIR}")
+        self.logger.info("=" * 70)
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+
+    def train(self, num_episodes: int):
+        """
+        Run the training loop for *num_episodes* episodes.
+
+        Args:
+            num_episodes: Number of episodes to train.
+        """
+        self.logger.info(f"Starting training — {num_episodes} episodes")
+
+        iterator = (
+            tqdm(range(1, num_episodes + 1), desc="Training", unit="ep")
+            if _TQDM
+            else range(1, num_episodes + 1)
+        )
+
+        try:
+            for episode in iterator:
+                self.current_episode = episode
+
+                try:
+                    ep_reward, ep_info = self._run_episode(training=True)
+                except KeyboardInterrupt:
+                    self.logger.info("Training interrupted by user.")
+                    self._save_checkpoint(episode, emergency=True)
+                    raise
+                except Exception as exc:
+                    self.logger.error(f"Episode {episode} error: {exc}")
+                    self.logger.debug(traceback.format_exc())
+                    continue
+
+                # Record metrics
+                self.metrics.add("episode_reward", ep_reward)
+                self.metrics.add("average_waiting_time",
+                                 ep_info.get("average_waiting_time", 0.0))
+                self.metrics.add("average_queue_length",
+                                 ep_info.get("total_queue_length", 0.0))
+                self.metrics.add("throughput",
+                                 ep_info.get("vehicles_passed", 0))
+
+                # Per-episode log
+                self.logger.info(
+                    f"Ep {episode:4d}/{num_episodes}  "
+                    f"reward={ep_reward:8.2f}  "
+                    f"wait={ep_info.get('average_waiting_time', 0):7.1f}  "
+                    f"queue={ep_info.get('total_queue_length', 0):6.1f}  "
+                    f"thru={ep_info.get('vehicles_passed', 0):4d}"
+                )
+
+                # DQN: sync target network
+                if hasattr(self.agent, "update_target_network"):
+                    freq = self.config.DQN_CONFIG.get("target_update", 10)
+                    if episode % freq == 0:
+                        self.agent.update_target_network()
+
+                # Save best model
+                if ep_reward > self.best_reward:
+                    self.best_reward = ep_reward
+                    self.episodes_without_improvement = 0
+                    self._save_best_model(episode, ep_reward)
+                else:
+                    self.episodes_without_improvement += 1
+
+                # Periodic checkpoint
+                if episode % self.config.SAVE_FREQUENCY == 0:
+                    self._save_checkpoint(episode)
+
+                # Periodic summary
+                if episode % 100 == 0:
+                    self._log_summary(episode, num_episodes)
+
+                # Early stopping
+                if self.episodes_without_improvement >= self.config.EARLY_STOPPING_PATIENCE:
+                    self.logger.info(
+                        f"Early stopping at episode {episode} "
+                        f"(no improvement for "
+                        f"{self.config.EARLY_STOPPING_PATIENCE} episodes)."
+                    )
+                    break
+
+        except KeyboardInterrupt:
+            self.logger.info("Exiting gracefully.")
+            sys.exit(0)
+
+        self.logger.info("=" * 70)
+        self.logger.info("TRAINING COMPLETE")
+        self._log_final_summary()
+        self._save_metrics()
+        self._plot_results()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _run_episode(self, training: bool = True) -> tuple[float, dict]:
+        """Execute one full episode."""
+        state, _ = self.env.reset()
+        ep_reward = 0.0
+        done = False
+        info: dict = {}
+        max_steps = self.config.EPISODE_LENGTH * 2
+
+        steps = 0
+        while not done and steps < max_steps:
+            action = self.agent.select_action(state, training=training)
+            next_state, reward, terminated, truncated, info = self.env.step(action)
+            done = terminated or truncated
+
+            if training:
+                loss = self.agent.train_step(state, action, reward, next_state, done)
+                if loss is not None:
+                    self.metrics.add("loss", float(loss))
+
+            state = next_state
+            ep_reward += reward
+            steps += 1
+            self.total_steps += 1
+
+        return ep_reward, info
+
+    def _save_best_model(self, episode: int, reward: float):
+        path = self.config.MODELS_DIR / f"{self.config.AGENT_TYPE}_best.pth"
+        try:
+            self.agent.save(str(path))
+            self.logger.info(
+                f"[OK] Best model saved  reward={reward:.2f}  (episode {episode})"
+            )
+        except Exception as exc:
+            self.logger.error(f"[FAIL] Could not save best model: {exc}")
+
+    def _save_checkpoint(self, episode: int, emergency: bool = False):
+        tag = "emergency" if emergency else f"ep{episode}"
+        path = (
+            self.config.RESULTS_DIR
+            / "checkpoints"
+            / f"{self.config.AGENT_TYPE}_{tag}.pth"
+        )
+        try:
+            self.agent.save(str(path))
+            self.logger.info(f"[OK] Checkpoint saved -> {path}")
+        except Exception as exc:
+            self.logger.error(f"[FAIL] Could not save checkpoint: {exc}")
+
+    def _log_summary(self, episode: int, total: int):
+        n = min(100, episode)
+        self.logger.info("-" * 70)
+        self.logger.info(f"Summary  ep {episode}/{total}")
+        self.logger.info(
+            f"  Avg reward  (last {n}): "
+            f"{self.metrics.get_mean('episode_reward', last_n=n):8.2f}"
+        )
+        self.logger.info(
+            f"  Avg wait    (last {n}): "
+            f"{self.metrics.get_mean('average_waiting_time', last_n=n):8.2f}"
+        )
+        self.logger.info(f"  Best reward so far  : {self.best_reward:8.2f}")
+        self.logger.info("-" * 70)
+
+    def _log_final_summary(self):
+        all_r = self.metrics.get("episode_reward")
+        if not all_r:
+            return
+        self.logger.info("FINAL STATISTICS")
+        self.logger.info(f"  Total episodes : {len(all_r)}")
+        self.logger.info(f"  Best reward    : {self.best_reward:.2f}")
+        self.logger.info(f"  Mean reward    : {np.mean(all_r):.2f}")
+        self.logger.info(f"  Std  reward    : {np.std(all_r):.2f}")
+
+    def _save_metrics(self):
+        path = self.config.RESULTS_DIR / "metrics.json"
+        try:
+            self.metrics.save(path)
+            self.logger.info(f"[OK] Metrics saved -> {path}")
+        except Exception as exc:
+            self.logger.warning(f"Could not save metrics: {exc}")
+
+    def _plot_results(self):
+        try:
+            from utils.visualizer import plot_training_curves
+            save = self.config.RESULTS_DIR / "plots" / f"{self.config.AGENT_TYPE}_training.png"
+            plot_training_curves(self.metrics, save_path=save)
+        except Exception as exc:
+            self.logger.warning(f"Could not plot results: {exc}")

utils/__init__.py

@@ -0,0 +1,15 @@
+"""
+Utils package.
+"""
+
+from .logger import setup_logger
+from .metrics import MetricsTracker
+from .visualizer import plot_training_curves, plot_comparison, plot_bar_comparison
+
+__all__ = [
+    "setup_logger",
+    "MetricsTracker",
+    "plot_training_curves",
+    "plot_comparison",
+    "plot_bar_comparison",
+]

utils/logger.py

@@ -0,0 +1,53 @@
+"""
+Logging utilities — creates consistent console + file loggers.
+"""
+
+import logging
+import sys
+from pathlib import Path
+
+
+def setup_logger(
+    name: str,
+    log_file: str | None = None,
+    level: int = logging.INFO,
+) -> logging.Logger:
+    """
+    Create (or retrieve) a named logger with console and optional file output.
+
+    Args:
+        name:     Logger name (used to namespace messages).
+        log_file: If given, also write to this path.
+        level:    Logging threshold (default INFO).
+
+    Returns:
+        Configured :class:`logging.Logger` instance.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Avoid duplicate handlers when called multiple times
+    if logger.handlers:
+        return logger
+
+    fmt = logging.Formatter(
+        "%(asctime)s | %(name)s | %(levelname)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # Console handler
+    ch = logging.StreamHandler(sys.stdout)
+    ch.setLevel(level)
+    ch.setFormatter(fmt)
+    logger.addHandler(ch)
+
+    # File handler (optional)
+    if log_file:
+        log_path = Path(log_file)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        fh = logging.FileHandler(log_file, encoding="utf-8")
+        fh.setLevel(level)
+        fh.setFormatter(fmt)
+        logger.addHandler(fh)
+
+    return logger

utils/metrics.py

@@ -0,0 +1,113 @@
+"""
+Metrics tracking — lightweight replacement for TensorBoard / W&B.
+
+Stores lists of scalar values keyed by metric name, and provides
+summary statistics and JSON serialisation.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+
+
+class MetricsTracker:
+    """
+    Accumulates scalar training metrics across episodes.
+
+    Usage::
+
+        tracker = MetricsTracker()
+        tracker.add("episode_reward", -920.3)
+        tracker.get_mean("episode_reward", last_n=100)
+        tracker.save("results/metrics.json")
+    """
+
+    def __init__(self):
+        self._data: dict[str, list] = defaultdict(list)
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    def add(self, name: str, value):
+        """Append *value* to the metric called *name*."""
+        self._data[name].append(value)
+
+    def get(self, name: str) -> list:
+        """Return all recorded values for *name* (empty list if absent)."""
+        return list(self._data.get(name, []))
+
+    def has(self, name: str) -> bool:
+        """True if at least one value for *name* has been recorded."""
+        return name in self._data and len(self._data[name]) > 0
+
+    def get_last(self, name: str, n: int = 1) -> list:
+        vals = self.get(name)
+        return vals[-n:]
+
+    def get_mean(self, name: str, last_n: int | None = None) -> float:
+        vals = self.get(name)
+        if not vals:
+            return 0.0
+        if last_n:
+            vals = vals[-last_n:]
+        return float(np.mean(vals))
+
+    def get_std(self, name: str, last_n: int | None = None) -> float:
+        vals = self.get(name)
+        if not vals:
+            return 0.0
+        if last_n:
+            vals = vals[-last_n:]
+        return float(np.std(vals))
+
+    def summary(self, name: str) -> dict:
+        vals = self.get(name)
+        if not vals:
+            return {}
+        return {
+            "count": len(vals),
+            "mean": float(np.mean(vals)),
+            "std": float(np.std(vals)),
+            "min": float(np.min(vals)),
+            "max": float(np.max(vals)),
+        }
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self, filepath: str | Path):
+        """Serialise to JSON."""
+        filepath = Path(filepath)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        with open(filepath, "w") as fh:
+            json.dump({k: list(v) for k, v in self._data.items()}, fh, indent=2)
+
+    def load(self, filepath: str | Path):
+        """Restore from a previously saved JSON file."""
+        with open(filepath) as fh:
+            raw = json.load(fh)
+        self._data = defaultdict(list, raw)
+
+    def reset(self):
+        """Clear all accumulated metrics."""
+        self._data.clear()
+
+    # ------------------------------------------------------------------
+    # Dunder helpers
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        lines = []
+        for name, vals in self._data.items():
+            if vals:
+                lines.append(
+                    f"  {name}: mean={np.mean(vals):.2f}  "
+                    f"std={np.std(vals):.2f}  n={len(vals)}"
+                )
+        return "MetricsTracker(\n" + "\n".join(lines) + "\n)"

utils/visualizer.py

@@ -0,0 +1,251 @@
+"""
+Visualisation utilities — training curves and comparison plots.
+
+Uses only Matplotlib (no Seaborn / Plotly dependency).
+All plots are saved to disk (non-interactive backend).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+try:
+    import matplotlib
+    matplotlib.use("Agg")          # Non-interactive backend (safe on servers)
+    import matplotlib.pyplot as plt
+    _MPL_OK = True
+except ImportError:
+    _MPL_OK = False
+    plt = None                     # type: ignore
+
+
+# ── Helper ────────────────────────────────────────────────────────────────────
+
+def _check_mpl():
+    if not _MPL_OK:
+        raise ImportError(
+            "matplotlib is required for plotting.\n"
+            "Install with:  pip install matplotlib"
+        )
+
+
+def _moving_average(values: list, window: int) -> list:
+    """Simple unweighted moving average."""
+    result = []
+    for i in range(len(values)):
+        start = max(0, i - window + 1)
+        result.append(float(np.mean(values[start : i + 1])))
+    return result
+
+
+# ── Public functions ──────────────────────────────────────────────────────────
+
+def plot_training_curves(metrics, save_path: str | Path | None = None) -> bool:
+    """
+    Plot four training metrics in a 2×2 grid and save to *save_path*.
+
+    Args:
+        metrics:   A :class:`MetricsTracker` instance.
+        save_path: Destination PNG path.  Shown interactively if None.
+
+    Returns:
+        True on success, False on failure.
+    """
+    try:
+        _check_mpl()
+
+        panel_cfg = [
+            ("episode_reward",       "Episode Reward",       "blue",   "Reward"),
+            ("average_waiting_time", "Avg Waiting Time",     "orange", "Waiting Time (s)"),
+            ("average_queue_length", "Avg Queue Length",     "red",    "Queue Length"),
+            ("throughput",           "Throughput",           "green",  "Vehicles Passed"),
+        ]
+
+        has_any = any(metrics.has(k) for k, *_ in panel_cfg)
+        if not has_any:
+            print("[WARN] No data available for plotting.")
+            return False
+
+        fig, axes = plt.subplots(2, 2, figsize=(15, 10))
+        fig.suptitle("Training Progress", fontsize=16, fontweight="bold")
+        axes_flat = axes.flatten()
+
+        for ax, (key, title, colour, ylabel) in zip(axes_flat, panel_cfg):
+            ax.set_title(title, fontsize=12, fontweight="bold")
+            ax.set_xlabel("Episode", fontsize=10)
+            ax.set_ylabel(ylabel, fontsize=10)
+            ax.grid(True, alpha=0.3)
+
+            if not metrics.has(key):
+                ax.text(0.5, 0.5, "No data", ha="center", va="center",
+                        transform=ax.transAxes, color="grey")
+                continue
+
+            vals = metrics.get(key)
+            eps = range(1, len(vals) + 1)
+            ax.plot(eps, vals, alpha=0.4, color=colour, linewidth=1, label="Raw")
+
+            if len(vals) >= 10:
+                w = min(50, max(10, len(vals) // 10))
+                ma = _moving_average(vals, w)
+                ax.plot(eps, ma, color=colour, linewidth=2,
+                        label=f"MA-{w}")
+                ax.legend(loc="best", fontsize=8)
+
+        plt.tight_layout()
+
+        if save_path:
+            save_path = Path(save_path)
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+            plt.savefig(save_path, dpi=150, bbox_inches="tight", facecolor="white")
+            print(f"[OK] Plot saved -> {save_path}")
+        else:
+            plt.show()
+
+        plt.close(fig)
+        return True
+
+    except ImportError as exc:
+        print(f"[WARN] {exc}")
+        return False
+    except Exception as exc:
+        print(f"[WARN] Plotting error: {exc}")
+        try:
+            plt.close("all")
+        except Exception:
+            pass
+        return False
+
+
+def plot_comparison(
+    results_dict: dict[str, list],
+    metric_name: str,
+    save_path: str | Path | None = None,
+) -> bool:
+    """
+    Overlay multiple result series on a single axes.
+
+    Args:
+        results_dict: ``{"Method Name": [values, …], …}``
+        metric_name:  Y-axis label / title suffix.
+        save_path:    Destination PNG path.
+
+    Returns:
+        True on success.
+    """
+    try:
+        _check_mpl()
+
+        if not results_dict:
+            print("[WARN] No data for comparison plot.")
+            return False
+
+        fig, ax = plt.subplots(figsize=(12, 6))
+
+        colours = ["blue", "green", "red", "orange", "purple"]
+        for i, (name, vals) in enumerate(results_dict.items()):
+            if vals:
+                ax.plot(range(1, len(vals) + 1), vals,
+                        label=name, linewidth=2, alpha=0.8,
+                        color=colours[i % len(colours)])
+
+        ax.set_xlabel("Episode", fontsize=12)
+        ax.set_ylabel(metric_name, fontsize=12)
+        ax.set_title(f"{metric_name} - Method Comparison",
+                     fontsize=14, fontweight="bold")
+        ax.legend(loc="best")
+        ax.grid(True, alpha=0.3)
+
+        plt.tight_layout()
+
+        if save_path:
+            save_path = Path(save_path)
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+            plt.savefig(save_path, dpi=150, bbox_inches="tight", facecolor="white")
+            print(f"[OK] Comparison plot saved -> {save_path}")
+        else:
+            plt.show()
+
+        plt.close(fig)
+        return True
+
+    except ImportError as exc:
+        print(f"[WARN] {exc}")
+        return False
+    except Exception as exc:
+        print(f"[WARN] Comparison plot error: {exc}")
+        try:
+            plt.close("all")
+        except Exception:
+            pass
+        return False
+
+
+def plot_bar_comparison(
+    method_scores: dict[str, float],
+    title: str = "Method Comparison",
+    ylabel: str = "Mean Reward",
+    save_path: str | Path | None = None,
+) -> bool:
+    """
+    Bar chart comparing scalar scores for different methods.
+
+    Args:
+        method_scores: {"Method": score, ...}
+        title:         Chart title.
+        ylabel:        Y-axis label.
+        save_path:     Destination PNG path.
+
+    Returns:
+        True on success.
+    """
+    try:
+        _check_mpl()
+
+        if not method_scores:
+            return False
+
+        names = list(method_scores.keys())
+        scores = [method_scores[n] for n in names]
+        colours = ["#4472C4", "#ED7D31", "#A9D18E"]
+
+        fig, ax = plt.subplots(figsize=(8, 5))
+        bars = ax.bar(names, scores,
+                      color=colours[: len(names)],
+                      edgecolor="white", linewidth=1.5)
+
+        # Value labels
+        for bar, score in zip(bars, scores):
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                bar.get_height() + (max(scores) - min(scores)) * 0.01,
+                f"{score:.2f}",
+                ha="center", va="bottom", fontsize=11, fontweight="bold",
+            )
+
+        ax.set_title(title, fontsize=14, fontweight="bold")
+        ax.set_ylabel(ylabel, fontsize=12)
+        ax.grid(axis="y", alpha=0.3)
+        ax.set_ylim(min(scores) * 1.05, max(scores) * 0.95)  # Tight y-range
+
+        plt.tight_layout()
+
+        if save_path:
+            save_path = Path(save_path)
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+            plt.savefig(save_path, dpi=150, bbox_inches="tight", facecolor="white")
+            print(f"[OK] Bar chart saved -> {save_path}")
+        else:
+            plt.show()
+
+        plt.close(fig)
+        return True
+
+    except ImportError as exc:
+        print(f"[WARN] {exc}")
+        return False
+    except Exception as exc:
+        print(f"[WARN] Bar chart error: {exc}")
+        return False