# satyatejachukka/adaptive-traffic-signal architecture

> Architecture diagram of the GitHub repository satyatejachukka/adaptive-traffic-signal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satyatejachukka/adaptive-traffic-signal
- Repository: https://github.com/satyatejachukka/adaptive-traffic-signal

## Overview

SeepageRL is a traffic-signal control research application: an interactive simulator and a headless experiment engine use seepage-aware state, constrained multi-profile vector Q-learning, and counterfactual explanations to select and audit signal actions. The benchmark runner evaluates controllers across scenarios and seeds; publication plots summarize benchmark results and seepage physics. Edges follow excerpts or README statements; unsampled simulation wiring is not inferred beyond those documented capabilities.

Main entry points: [`simulation.py`](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/simulation.py) (Interactive Simulator), [`headless_runner.py`](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/headless_runner.py) (Headless Environment), [`rl_state.py`](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/rl_state.py) (Seepage State), [`run_experiments.py`](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/run_experiments.py) (Ablation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physics["Traffic Physics"]
  node_state_physics["Seepage State<br/>[rl_state.py]"]
  node_config["Control Config<br/>[config.py]"]
end

subgraph group_control["Control and Audit"]
  node_agent["Vector Q Learner<br/>[rl_agent.py]"]
  node_reward["Vector Rewards<br/>[reward.py]"]
  node_audit["Counterfactual Audit"]
end

subgraph group_runtime["Simulation Runtimes"]
  node_interactive["Interactive Simulator<br/>[simulation.py]"]
  node_traffic_ui["Traffic and Telemetry UI<br/>[simulation.py]"]
  node_headless["Headless Environment<br/>[headless_runner.py]"]
  node_trainer["Vector Agent Trainer<br/>[headless_runner.py]"]
end

subgraph group_research["Research Outputs"]
  node_experiments["Ablation Runner<br/>[run_experiments.py]"]
  node_results["Benchmark Results"]
  node_figures["Research Figures"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_interactive
node_interactive -->|"renders"| node_traffic_ui
node_interactive -->|"selects actions"| node_agent
node_interactive -->|"encodes state"| node_state_physics
node_interactive -->|"shows explanations"| node_audit
node_interactive -->|"uses settings"| node_config
node_headless -->|"uses settings"| node_config
node_headless -->|"builds state"| node_state_physics
node_headless -->|"uses learner"| node_agent
node_trainer -->|"trains in"| node_headless
node_experiments -->|"runs scenarios"| node_headless
node_experiments -->|"evaluates policies"| node_agent
node_experiments -->|"uses parameters"| node_state_physics
node_experiments -->|"writes results"| node_results
node_figures -->|"plots physics"| node_state_physics
node_figures -->|"reads results"| node_results
node_reward -->|"delegates reward"| node_agent
node_reward -->|"uses parameters"| node_state_physics

click node_state_physics "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/rl_state.py"
click node_config "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/config.py"
click node_agent "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/rl_agent.py"
click node_reward "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/reward.py"
click node_audit "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/counterfactual_explainer.py"
click node_interactive "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/simulation.py"
click node_traffic_ui "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/simulation.py"
click node_headless "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/headless_runner.py"
click node_trainer "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/headless_runner.py"
click node_experiments "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/run_experiments.py"
click node_results "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/experiments/benchmark_results.csv"
click node_figures "https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/plot_paper_figures.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_state_physics,node_config toneBlue
class node_agent,node_reward,node_audit toneAmber
class node_interactive,node_traffic_ui,node_headless,node_trainer toneMint
class node_experiments,node_results,node_figures toneRose
class node_operator toneIndigo
```

## Components

### Traffic Physics

- [Seepage State](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/rl_state.py): `rl_state.py`
- [Control Config](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/config.py): `config.py`

### Control and Audit

- [Vector Q Learner](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/rl_agent.py): `rl_agent.py`
- [Vector Rewards](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/reward.py): `reward.py`
- [Counterfactual Audit](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/counterfactual_explainer.py): `counterfactual_explainer.py`

### Simulation Runtimes

- [Interactive Simulator](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/simulation.py): `simulation.py`
- [Traffic and Telemetry UI](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/simulation.py): `simulation.py`
- [Headless Environment](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/headless_runner.py): `headless_runner.py`
- [Vector Agent Trainer](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/headless_runner.py): `headless_runner.py`

### Research Outputs

- [Ablation Runner](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/run_experiments.py): `run_experiments.py`
- [Benchmark Results](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/experiments/benchmark_results.csv): `experiments/benchmark_results.csv`
- [Research Figures](https://github.com/satyatejachukka/adaptive-traffic-signal/blob/main/plot_paper_figures.py): `plot_paper_figures.py`

### Other components

- **Operator**

## Connections

- Operator → Interactive Simulator: runs (evidence: `readme.md`)
- Interactive Simulator → Traffic and Telemetry UI: renders (evidence: `readme.md`)
- Interactive Simulator → Vector Q Learner: selects actions (evidence: `simulation.py`)
- Interactive Simulator → Seepage State: encodes state (evidence: `simulation.py`)
- Interactive Simulator → Counterfactual Audit: shows explanations (evidence: `readme.md`)
- Interactive Simulator → Control Config: uses settings (evidence: `simulation.py`)
- Headless Environment → Control Config: uses settings (evidence: `headless_runner.py`)
- Headless Environment → Seepage State: builds state (evidence: `headless_runner.py`)
- Headless Environment → Vector Q Learner: uses learner (evidence: `headless_runner.py`)
- Vector Agent Trainer → Headless Environment: trains in (evidence: `readme.md`)
- Ablation Runner → Headless Environment: runs scenarios (evidence: `run_experiments.py`)
- Ablation Runner → Vector Q Learner: evaluates policies (evidence: `run_experiments.py`)
- Ablation Runner → Seepage State: uses parameters (evidence: `run_experiments.py`)
- Ablation Runner → Benchmark Results: writes results (evidence: `readme.md`)
- Research Figures → Seepage State: plots physics (evidence: `plot_paper_figures.py`)
- Research Figures → Benchmark Results: reads results (evidence: `plot_paper_figures.py`)
- Vector Rewards → Vector Q Learner: delegates reward (evidence: `reward.py`)
- Vector Rewards → Seepage State: uses parameters (evidence: `reward.py`)