# andreavidali/deep-qlearning-agent-for-traffic-signal-control architecture

> Architecture diagram of the GitHub repository andreavidali/deep-qlearning-agent-for-traffic-signal-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control
- Repository: https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control

## Overview

TLCS trains and evaluates a DQN that controls a single SUMO intersection. The user starts a train or test run; validated settings configure the run, and each episode generates traffic routes, observes the simulation, chooses signal phases, and records rewards and queue statistics. Training turns episode history into replay samples and updates a neural network; testing loads a trained model. Runs save model/settings artifacts and plots. The graph follows documented capabilities and sampled call sites; SUMO is external, and unsampled internals are represented only where the README supports them.

Main entry points: [`src/tlcs/main.py`](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/main.py) (Run orchestration), [`src/tlcs/agent.py`](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/agent.py) (Epsilon-greedy agent), [`src/tlcs/env.py`](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/env.py) (SUMO environment), [`src/tlcs/model.py`](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/model.py) (Q-network)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run entry"]
  node_cli["Train/test CLI<br/>[cli.py]"]
  node_settings["Settings validation<br/>[settings.py]"]
  node_main["Run orchestration<br/>[main.py]"]
end

subgraph group_simulation["Simulation"]
  node_episode["Episode loop<br/>[episode.py]"]
  node_environment["SUMO environment<br/>[env.py]"]
  node_generator["Route generation<br/>[generator.py]"]
  node_scenario["Intersection scenario"]
end

subgraph group_learning["DQN learning"]
  node_agent["Epsilon-greedy agent<br/>[agent.py]"]
  node_model["Q-network<br/>[model.py]"]
  node_memory["Replay buffer<br/>[memory.py]"]
end

subgraph group_results["Run outputs"]
  node_runfiles["Run artifacts<br/>[main.py]"]
  node_plots["Metrics plots<br/>[plots.py]"]
  node_modelstore["Trained model<br/>[model.py]"]
end

node_user(("Operator"))
node_sumo["SUMO simulator"]
node_trainingconfig["Training YAML"]
node_testingconfig["Testing YAML"]

node_user -->|"starts run"| node_cli
node_cli -->|"dispatches"| node_main
node_cli -->|"selects config"| node_settings
node_main -->|"loads settings"| node_settings
node_trainingconfig -->|"training values"| node_settings
node_testingconfig -->|"testing values"| node_settings
node_main -->|"runs episodes"| node_episode
node_main -->|"configures"| node_environment
node_main -->|"creates or loads"| node_agent
node_main -->|"creates buffer"| node_memory
node_episode -->|"observes and acts"| node_environment
node_episode -->|"requests action"| node_agent
node_environment -->|"generates routes"| node_generator
node_generator -->|"writes route file"| node_scenario
node_environment -->|"controls simulation"| node_sumo
node_scenario -->|"configures"| node_sumo
node_main -->|"adds transitions"| node_memory
node_main -->|"replays batches"| node_agent
node_agent -->|"samples transitions"| node_memory
node_agent -->|"predicts and trains"| node_model
node_main -->|"saves model"| node_model
node_model -->|"serializes weights"| node_modelstore
node_main -->|"copies settings"| node_runfiles
node_main -->|"saves metrics"| node_plots
node_plots -->|"writes plots and data"| node_runfiles
node_modelstore -->|"loads for testing"| node_model

click node_cli "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/cli.py"
click node_settings "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/settings.py"
click node_main "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/main.py"
click node_episode "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/episode.py"
click node_environment "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/env.py"
click node_generator "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/generator.py"
click node_scenario "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/intersection/sumo_config.sumocfg"
click node_agent "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/agent.py"
click node_model "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/model.py"
click node_memory "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/memory.py"
click node_runfiles "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/main.py"
click node_plots "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/plots.py"
click node_modelstore "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/model.py"
click node_trainingconfig "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/settings/training_settings.yaml"
click node_testingconfig "https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/settings/testing_settings.yaml"

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_cli,node_settings,node_main toneBlue
class node_episode,node_environment,node_generator,node_scenario toneAmber
class node_agent,node_model,node_memory toneMint
class node_runfiles,node_plots,node_modelstore toneRose
class node_user,node_sumo toneIndigo
class node_trainingconfig,node_testingconfig toneTeal
```

## Components

### Run entry

- [Train/test CLI](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/cli.py): `src/tlcs/cli.py`
- [Settings validation](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/settings.py): `src/tlcs/settings.py`
- [Run orchestration](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/main.py): `src/tlcs/main.py`

### Simulation

- [Episode loop](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/episode.py): `src/tlcs/episode.py`
- [SUMO environment](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/env.py): `src/tlcs/env.py`
- [Route generation](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/generator.py): `src/tlcs/generator.py`
- [Intersection scenario](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/intersection/sumo_config.sumocfg): `intersection/sumo_config.sumocfg`

### DQN learning

- [Epsilon-greedy agent](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/agent.py): `src/tlcs/agent.py`
- [Q-network](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/model.py): `src/tlcs/model.py`
- [Replay buffer](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/memory.py): `src/tlcs/memory.py`

### Run outputs

- [Run artifacts](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/main.py): `src/tlcs/main.py`
- [Metrics plots](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/plots.py): `src/tlcs/plots.py`
- [Trained model](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/src/tlcs/model.py): `src/tlcs/model.py`

### Other components

- **Operator**
- **SUMO simulator**
- [Training YAML](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/settings/training_settings.yaml): `settings/training_settings.yaml`
- [Testing YAML](https://github.com/andreavidali/deep-qlearning-agent-for-traffic-signal-control/blob/master/settings/testing_settings.yaml): `settings/testing_settings.yaml`

## Connections

- Operator → Train/test CLI: starts run
- Train/test CLI → Run orchestration: dispatches
- Train/test CLI → Settings validation: selects config
- Run orchestration → Settings validation: loads settings
- Training YAML → Settings validation: training values
- Testing YAML → Settings validation: testing values
- Run orchestration → Episode loop: runs episodes
- Run orchestration → SUMO environment: configures
- Run orchestration → Epsilon-greedy agent: creates or loads
- Run orchestration → Replay buffer: creates buffer
- Episode loop → SUMO environment: observes and acts
- Episode loop → Epsilon-greedy agent: requests action
- SUMO environment → Route generation: generates routes
- Route generation → Intersection scenario: writes route file
- SUMO environment → SUMO simulator: controls simulation
- Intersection scenario → SUMO simulator: configures
- Run orchestration → Replay buffer: adds transitions
- Run orchestration → Epsilon-greedy agent: replays batches
- Epsilon-greedy agent → Replay buffer: samples transitions
- Epsilon-greedy agent → Q-network: predicts and trains
- Run orchestration → Q-network: saves model
- Q-network → Trained model: serializes weights
- Run orchestration → Run artifacts: copies settings
- Run orchestration → Metrics plots: saves metrics
- Metrics plots → Run artifacts: writes plots and data
- Trained model → Q-network: loads for testing