# sahityabiswas/cityflow architecture

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

- Interactive diagram: https://gitdiagram.com/sahityabiswas/cityflow
- Repository: https://github.com/sahityabiswas/cityflow

## Overview

#### Purpose and Entry Point
This is a local Python reinforcement-learning simulator for adaptive control of a single four-way traffic intersection. Running `main.py` starts training and visualization in a PyGame window. The executable path is `main.py`, which delegates the simulation lifecycle to `src/simulation.py`.

#### Runtime Composition
The system runs as one in-process Python application, with:
- PyGame for the interactive simulation, frame rendering, and HUD.
- PyTorch for the Deep Q-Network (DQN) and optimization.
- No server, database, cloud infrastructure, or external runtime service is indicated.
Dependencies are declared in `requirements.txt`; core modules reside under `src/`.

#### Configuration Boundary
`src/config.py` centralizes simulation layout/constants and RL hyperparameters, including learning rate, discount factor, batch size, replay capacity, and epsilon schedule. This module is the shared policy/configuration boundary consumed by the environment, agent, model, and simulation:
- `src/config.py`
- `src/simulation.py`
- `src/agent.py`

#### Traffic Environment and State Transition
`src/environment.py` owns the traffic-domain simulation: lane queues, vehicle spawning and movement, collision-related checks, signal application, state extraction, and reward calculation. Its state is a four-value lane-queue observation (north, south, east, west). An action selects one of six permitted traffic-light phases. The environment advances vehicles, handles emergency-vehicle priority, and returns the reward signal based on queue and wait-time reduction:
- `src/environment.py`
- `src/config.py`

#### DQN Model
`src/model.py` defines the PyTorch Q-network used to estimate action values from the four-dimensional traffic state. It is intentionally separated from learning policy and simulation concerns: the model supplies forward inference and trainable parameters, while the agent determines exploration and invokes optimization:
- `src/model.py`
- `src/agent.py`

#### Learning Agent and Replay Boundary
`src/agent.py` implements the reinforcement-learning controller. It performs epsilon-greedy selection between random phases and Q-network exploitation, stores `(state, action, reward, next_state)` transitions in a replay buffer, samples batches after sufficient experience exists, updates the DQN, and decays epsilon. This is the boundary between environment feedback and model training:
- `src/agent.py`
- `src/model.py`
- `src/environment.py`

#### Simulation Orchestration and Control Flow
`src/simulation.py` coordinates repeated simulated “days”: initialize PyGame/environment/agent, spawn and progress traffic, obtain state, request an action, apply the phase, step the environment, record the transition, train the agent, and render the intersection plus training metrics. Day-level reward and waiting-time statistics feed the live learning curves and HUD. Emergency detection may override normal selected signaling before reward and replay storage:
- `src/simulation.py`
- `src/environment.py`
- `src/agent.py`

#### Supporting Artifacts
`notebooks/SCTLC.ipynb` is a reference/exploratory notebook rather than the application entry path. `docs/Report_Team_SSP.pdf` contains project research documentation. The runnable architecture is concentrated in `main.py` and the five core `src/` modules.

Main entry points: [`src/agent.py`](https://github.com/sahityabiswas/cityflow/blob/main/src/agent.py) (DQN Agent), [`src/simulation.py`](https://github.com/sahityabiswas/cityflow/blob/main/src/simulation.py) (Simulation Orchestrator), [`src/environment.py`](https://github.com/sahityabiswas/cityflow/blob/main/src/environment.py) (Traffic Environment), [`src/config.py`](https://github.com/sahityabiswas/cityflow/blob/main/src/config.py) (Simulation & RL Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Interactive Runtime"]
  node_main["Application Entry<br/>Python entry point<br/>[main.py]"]
  node_simulation["Simulation Orchestrator<br/>Python module<br/>[simulation.py]"]
  node_pygame["PyGame Window &amp; HUD<br/>interactive UI"]
end

subgraph group_rl["DQN Learning"]
  node_agent["DQN Agent<br/>RL controller<br/>[agent.py]"]
  node_replay[("Replay Buffer<br/>experience memory")]
  node_model["PyTorch Q-Network<br/>neural network<br/>[model.py]"]
end

subgraph group_traffic["Traffic Domain"]
  node_environment["Traffic Environment<br/>simulation domain<br/>[environment.py]"]
  node_traffic_state["Lane Queue State<br/>4-value observation"]
  node_phase_control{{"Traffic Phase Control<br/>6-action space"}}
  node_reward(("Queue &amp; Wait Reward<br/>reward signal"))
end

node_config["Simulation &amp; RL Config<br/>configuration module<br/>[config.py]"]
node_notebook["Exploratory Notebook<br/>reference notebook<br/>[SCTLC.ipynb]"]
node_report["Project Report<br/>documentation"]

node_main -->|"starts"| node_simulation
node_simulation -->|"renders"| node_pygame
node_simulation -->|"coordinates steps"| node_environment
node_simulation -->|"requests action / trains"| node_agent
node_environment -->|"extracts"| node_traffic_state
node_traffic_state -->|"observation"| node_agent
node_agent -->|"selects phase"| node_phase_control
node_phase_control -->|"applies signals"| node_environment
node_environment -->|"calculates"| node_reward
node_reward -->|"feedback"| node_agent
node_agent -->|"stores transitions"| node_replay
node_replay -->|"samples batches"| node_agent
node_agent -->|"optimizes"| node_model
node_model -->|"Q-values"| node_agent
node_config -.->|"runtime settings"| node_simulation
node_config -.->|"layout/constants"| node_environment
node_config -.->|"RL hyperparameters"| node_agent

click node_main "https://github.com/sahityabiswas/cityflow/blob/main/main.py"
click node_simulation "https://github.com/sahityabiswas/cityflow/blob/main/src/simulation.py"
click node_config "https://github.com/sahityabiswas/cityflow/blob/main/src/config.py"
click node_environment "https://github.com/sahityabiswas/cityflow/blob/main/src/environment.py"
click node_agent "https://github.com/sahityabiswas/cityflow/blob/main/src/agent.py"
click node_model "https://github.com/sahityabiswas/cityflow/blob/main/src/model.py"
click node_notebook "https://github.com/sahityabiswas/cityflow/blob/main/notebooks/SCTLC.ipynb"
click node_report "https://github.com/sahityabiswas/cityflow/blob/main/docs/Report_Team_SSP.pdf"

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_main,node_simulation,node_pygame toneBlue
class node_agent,node_replay,node_model toneAmber
class node_environment,node_traffic_state,node_phase_control,node_reward toneMint
class node_config,node_notebook,node_report toneNeutral
```

## Components

### Interactive Runtime

- [Application Entry](https://github.com/sahityabiswas/cityflow/blob/main/main.py): Python entry point · Starts training and visualization. · `main.py`
- [Simulation Orchestrator](https://github.com/sahityabiswas/cityflow/blob/main/src/simulation.py): Python module · Runs day cycles, control flow, metrics, and rendering. · `src/simulation.py`
- **PyGame Window & HUD**: interactive UI · Renders the intersection and live learning metrics.

### DQN Learning

- [DQN Agent](https://github.com/sahityabiswas/cityflow/blob/main/src/agent.py): RL controller · Selects actions, records experience, trains, and decays epsilon. · `src/agent.py`
- **Replay Buffer**: experience memory · Stores and batches state-transition tuples.
- [PyTorch Q-Network](https://github.com/sahityabiswas/cityflow/blob/main/src/model.py): neural network · Estimates six action values from traffic state. · `src/model.py`

### Traffic Domain

- [Traffic Environment](https://github.com/sahityabiswas/cityflow/blob/main/src/environment.py): simulation domain · Owns lanes, vehicles, signals, state transitions, and rewards. · `src/environment.py`
- **Lane Queue State**: 4-value observation · North, south, east, and west queue values.
- **Traffic Phase Control**: 6-action space · Applies permitted signal phases with emergency priority.
- **Queue & Wait Reward**: reward signal · Rewards queue and wait-time reduction.

### Other components

- [Simulation & RL Config](https://github.com/sahityabiswas/cityflow/blob/main/src/config.py): configuration module · Shared layout constants and learning hyperparameters. · `src/config.py`
- [Exploratory Notebook](https://github.com/sahityabiswas/cityflow/blob/main/notebooks/SCTLC.ipynb): reference notebook · Reference and exploratory work outside the runtime path. · `notebooks/SCTLC.ipynb`
- [Project Report](https://github.com/sahityabiswas/cityflow/blob/main/docs/Report_Team_SSP.pdf): documentation · `docs/Report_Team_SSP.pdf`

## Connections

- Application Entry → Simulation Orchestrator: starts
- Simulation Orchestrator → PyGame Window & HUD: renders
- Simulation Orchestrator → Traffic Environment: coordinates steps
- Simulation Orchestrator → DQN Agent: requests action / trains
- Traffic Environment → Lane Queue State: extracts
- Lane Queue State → DQN Agent: observation
- DQN Agent → Traffic Phase Control: selects phase
- Traffic Phase Control → Traffic Environment: applies signals
- Traffic Environment → Queue & Wait Reward: calculates
- Queue & Wait Reward → DQN Agent: feedback
- DQN Agent → Replay Buffer: stores transitions
- Replay Buffer → DQN Agent: samples batches
- DQN Agent → PyTorch Q-Network: optimizes
- PyTorch Q-Network → DQN Agent: Q-values
- Simulation & RL Config → Simulation Orchestrator: runtime settings
- Simulation & RL Config → Traffic Environment: layout/constants
- Simulation & RL Config → DQN Agent: RL hyperparameters