# teodortodorovski01/diploma-sumo architecture

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

- Interactive diagram: https://gitdiagram.com/teodortodorovski01/diploma-sumo
- Repository: https://github.com/teodortodorovski01/diploma-sumo

## Overview

This repository is a SUMO traffic-and-ambulance simulation for central Skopje and the wider Skopje road network. The principal workflow is to configure a scenario, generate passenger trips and (for Skopje) an ambulance route, then launch the controller, which runs SUMO, periodically replans the ambulance route, and optionally preempts signals. Simulation trip information is the main result. The graph includes documented map, blockage, signal-cycle, and GUI/headless capabilities. Source excerpts show controller internals; scenario-launch relationships rely partly on the README because its implementation excerpt is incomplete.

Main entry points: [`centar/control.py`](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py) (Simulation controller), [`centar/scenario.py`](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py) (Scenario generator), [`skopje/net.net.xml.gz`](https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/net.net.xml.gz) (Skopje map), [`skopje/map.osm`](https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/map.osm) (Skopje OSM extract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scenario["Scenario setup"]
  node_generator["Scenario generator<br/>[scenario.py]"]
  node_passenger_trips["Passenger trips<br/>[scenario.py]"]
  node_ambulance_route["Ambulance route<br/>[scenario.py]"]
  node_blockage["Optional blockage<br/>[scenario.py]"]
end

subgraph group_networks["Road networks"]
  node_centar_map["Central-area map<br/>[net.net.xml]"]
  node_skopje_map["Skopje map<br/>[net.net.xml.gz]"]
  node_osm["Skopje OSM extract<br/>[map.osm]"]
  node_sumo_config["Central SUMO config<br/>[run.sumocfg]"]
  node_skopje_config["Skopje SUMO config<br/>[skopje.sumocfg]"]
end

subgraph group_control["Simulation control"]
  node_sumo["SUMO runtime"]
  node_controller["Simulation controller<br/>[control.py]"]
  node_route_planner["Dynamic route planner<br/>[control.py]"]
  node_signal_cycles["Signal-cycle tuning<br/>[control.py]"]
  node_signal_preemption["Signal preemption<br/>[control.py]"]
end

subgraph group_results["Simulation outputs"]
  node_tripinfo["Trip information<br/>[scenario.py]"]
end

node_user(("Scenario operator"))
node_gui["SUMO-GUI"]

node_user -->|"configures"| node_generator
node_generator -->|"generates"| node_passenger_trips
node_generator -->|"generates"| node_ambulance_route
node_generator -->|"may add"| node_blockage
node_generator -->|"launches"| node_controller
node_generator -->|"configures output"| node_tripinfo
node_generator -->|"selects"| node_centar_map
node_generator -->|"selects"| node_skopje_map
node_osm -->|"source data"| node_skopje_map
node_controller -->|"starts"| node_sumo
node_controller -->|"loads routes"| node_passenger_trips
node_controller -->|"loads route"| node_ambulance_route
node_controller -->|"uses by default"| node_sumo_config
node_controller -->|"replans with"| node_route_planner
node_route_planner -->|"reads travel times"| node_sumo
node_route_planner -->|"updates ambulance route"| node_sumo
node_controller -->|"configures when enabled"| node_signal_cycles
node_signal_cycles -->|"sets signal programs"| node_sumo
node_controller -->|"runs when enabled"| node_signal_preemption
node_signal_preemption -->|"requests green phases"| node_sumo
node_controller -->|"requests recording"| node_tripinfo
node_controller -.->|"starts optionally"| node_gui
node_generator -->|"selects for Skopje"| node_skopje_config

click node_generator "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py"
click node_passenger_trips "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py"
click node_ambulance_route "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py"
click node_blockage "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py"
click node_centar_map "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/net.net.xml"
click node_skopje_map "https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/net.net.xml.gz"
click node_osm "https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/map.osm"
click node_sumo_config "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/run.sumocfg"
click node_skopje_config "https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/skopje.sumocfg"
click node_controller "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py"
click node_route_planner "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py"
click node_signal_cycles "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py"
click node_signal_preemption "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py"
click node_tripinfo "https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.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_generator,node_passenger_trips,node_ambulance_route,node_blockage,node_gui toneBlue
class node_centar_map,node_skopje_map,node_osm,node_sumo_config,node_skopje_config toneAmber
class node_sumo,node_controller,node_route_planner,node_signal_cycles,node_signal_preemption toneMint
class node_tripinfo toneRose
class node_user toneIndigo
```

## Components

### Scenario setup

- [Scenario generator](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py): `centar/scenario.py`
- [Passenger trips](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py): `centar/scenario.py`
- [Ambulance route](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py): `centar/scenario.py`
- [Optional blockage](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py): `centar/scenario.py`

### Road networks

- [Central-area map](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/net.net.xml): `centar/net.net.xml`
- [Skopje map](https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/net.net.xml.gz): `skopje/net.net.xml.gz`
- [Skopje OSM extract](https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/map.osm): `skopje/map.osm`
- [Central SUMO config](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/run.sumocfg): `centar/run.sumocfg`
- [Skopje SUMO config](https://github.com/teodortodorovski01/diploma-sumo/blob/main/skopje/skopje.sumocfg): `skopje/skopje.sumocfg`

### Simulation control

- **SUMO runtime**
- [Simulation controller](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py): `centar/control.py`
- [Dynamic route planner](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py): `centar/control.py`
- [Signal-cycle tuning](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py): `centar/control.py`
- [Signal preemption](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/control.py): `centar/control.py`

### Simulation outputs

- [Trip information](https://github.com/teodortodorovski01/diploma-sumo/blob/main/centar/scenario.py): `centar/scenario.py`

### Other components

- **Scenario operator**
- **SUMO-GUI**

## Connections

- Scenario operator → Scenario generator: configures (evidence: `README.md`)
- Scenario generator → Passenger trips: generates (evidence: `README.md`)
- Scenario generator → Ambulance route: generates (evidence: `README.md`)
- Scenario generator → Optional blockage: may add (evidence: `README.md`)
- Scenario generator → Simulation controller: launches (evidence: `README.md`)
- Scenario generator → Trip information: configures output (evidence: `centar/scenario.py`)
- Scenario generator → Central-area map: selects (evidence: `centar/scenario.py`)
- Scenario generator → Skopje map: selects (evidence: `centar/scenario.py`)
- Skopje OSM extract → Skopje map: source data (evidence: `README.md`)
- Simulation controller → SUMO runtime: starts (evidence: `centar/control.py`)
- Simulation controller → Passenger trips: loads routes (evidence: `README.md`)
- Simulation controller → Ambulance route: loads route (evidence: `README.md`)
- Simulation controller → Central SUMO config: uses by default (evidence: `centar/control.py`)
- Simulation controller → Dynamic route planner: replans with (evidence: `centar/control.py`)
- Dynamic route planner → SUMO runtime: reads travel times (evidence: `centar/control.py`)
- Dynamic route planner → SUMO runtime: updates ambulance route (evidence: `centar/control.py`)
- Simulation controller → Signal-cycle tuning: configures when enabled (evidence: `centar/control.py`)
- Signal-cycle tuning → SUMO runtime: sets signal programs (evidence: `centar/control.py`)
- Simulation controller → Signal preemption: runs when enabled (evidence: `centar/control.py`)
- Signal preemption → SUMO runtime: requests green phases (evidence: `centar/control.py`)
- Simulation controller → Trip information: requests recording (evidence: `centar/control.py`)
- Simulation controller → SUMO-GUI: starts optionally (evidence: `centar/control.py`)
- Scenario generator → Skopje SUMO config: selects for Skopje (evidence: `README.md`)
