# irenemarta/macromobilitysumoagent architecture

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

- Interactive diagram: https://gitdiagram.com/irenemarta/macromobilitysumoagent
- Repository: https://github.com/irenemarta/macromobilitysumoagent

## Overview

Macro Mobility SUMO Agent combines a conversational scenario interface with a traffic digital-twin pipeline. A user describes a what-if change; the agent validates the request, resolves it against the road index, and submits a scenario for simulation and comparison with a baseline. The twin prepares demand and zones, performs iterative assignment and SUMO simulation, and provides analysis and sensor-validation capabilities. Relationships for unsampled modules are included only where the README or SOURCE INDEX supports them; implementation details of those modules were not inspected.

Main entry points: [`src/dtsumo/whatif/run.py`](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/run.py) (What-if runner), [`src/agent/agente.py`](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/agente.py) (Request agent), [`src/agent/motore.py`](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/motore.py) (Scenario engine), [`src/dtsumo/inputs/config.py`](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/config.py) (Twin configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Conversational agent"]
  node_web["Web and CLI<br/>[app.py]"]
  node_conversation["Request agent<br/>[agente.py]"]
  node_settings["Agent settings<br/>[configurazione.py]"]
  node_roadindex["Road index<br/>[indice_rete.py]"]
  node_resolve["Request resolution<br/>[risolvi.py]"]
  node_engine["Scenario engine<br/>[motore.py]"]
  node_siminterface["Simulation interface<br/>[simula.py]"]
end

subgraph group_prep["Twin inputs"]
  node_inputs["Twin configuration<br/>[config.py]"]
  node_database[("Input database<br/>[database.py]")]
  node_odinputs["OD preparation<br/>[dayODs.py]"]
  node_zones["TAZ zones<br/>[taz_zones.py]"]
  node_entities["Assignment entities<br/>[entities.py]"]
end

subgraph group_simulation["Assignment and scenarios"]
  node_assignment["Assignment orchestration<br/>[assignment.py]"]
  node_marouter["Iterative assignment<br/>[marouter_cycle.py]"]
  node_odextension["OD extension<br/>[od_extension.py]"]
  node_commands["SUMO tool commands<br/>[cmd.py]"]
  node_scenario["Scenario interpretation<br/>[scenario.py]"]
  node_network["Scenario network<br/>[network.py]"]
  node_whatifrun["What-if runner<br/>[run.py]"]
end

subgraph group_analysis["Analysis and validation"]
  node_detectors["Detector processing<br/>[detectors.py]"]
  node_compare["Scenario comparison<br/>[compare.py]"]
  node_sensors["Sensor analysis<br/>[sensors.py]"]
  node_validation["Sensor validation"]
  node_maps["Result maps<br/>[maps.py]"]
  node_results["SUMO results<br/>[sumoResults.py]"]
end

node_user(("User"))
node_sumo{{"SUMO simulator"}}
node_externaldata[("CinqueT sensor data")]

node_user -->|"submits request"| node_web
node_web -->|"routes interaction"| node_conversation
node_conversation -->|"loads settings"| node_settings
node_conversation -->|"looks up roads"| node_roadindex
node_conversation -->|"validates request"| node_resolve
node_conversation -->|"invokes tools"| node_engine
node_engine -->|"uses scenario format"| node_scenario
node_engine -->|"runs scenario"| node_whatifrun
node_engine -->|"reads configuration"| node_inputs
node_web -->|"starts simulation"| node_siminterface
node_siminterface -->|"coordinates execution"| node_engine
node_siminterface -->|"compares results"| node_compare
node_whatifrun -->|"resolves interventions"| node_scenario
node_whatifrun -->|"builds scenario network"| node_network
node_whatifrun -->|"runs assignment"| node_assignment
node_whatifrun -->|"extends demand"| node_odextension
node_whatifrun -->|"uses detectors"| node_detectors
node_whatifrun -->|"runs simulation"| node_sumo
node_assignment -->|"uses zones"| node_zones
node_assignment -->|"runs cycles"| node_marouter
node_assignment -->|"extends OD"| node_odextension
node_marouter -->|"invokes tools"| node_commands
node_marouter -->|"simulates rounds"| node_sumo
node_zones -->|"builds context"| node_entities
node_odextension -->|"invokes routing"| node_commands
node_database -->|"uses paths"| node_inputs
node_odinputs -->|"uses settings"| node_inputs
node_compare -->|"reads settings"| node_inputs
node_validation -->|"uses map analysis"| node_maps
node_validation -->|"uses sensor analysis"| node_sensors
node_validation -->|"uses detector data"| node_detectors
node_validation -->|"validates against"| node_externaldata
node_maps -->|"uses detector data"| node_detectors
node_results -->|"uses settings"| node_inputs

click node_web "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/app.py"
click node_conversation "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/agente.py"
click node_settings "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/configurazione.py"
click node_roadindex "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/indice_rete.py"
click node_resolve "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/risolvi.py"
click node_engine "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/motore.py"
click node_siminterface "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/simula.py"
click node_inputs "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/config.py"
click node_database "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/database.py"
click node_odinputs "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/dayODs.py"
click node_zones "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/taz_zones.py"
click node_entities "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/modules/entities.py"
click node_assignment "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/assignment.py"
click node_marouter "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/marouter_cycle.py"
click node_odextension "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/od_extension.py"
click node_commands "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/cmd.py"
click node_scenario "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/scenario.py"
click node_network "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/network.py"
click node_whatifrun "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/run.py"
click node_detectors "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/tools/detectors.py"
click node_compare "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/compare.py"
click node_sensors "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sensors.py"
click node_validation "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sensors_validation.py"
click node_maps "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/maps.py"
click node_results "https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sumoResults.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_web,node_conversation,node_settings,node_roadindex,node_resolve,node_engine,node_siminterface,node_user toneBlue
class node_inputs,node_database,node_odinputs,node_zones,node_entities,node_externaldata toneAmber
class node_assignment,node_marouter,node_odextension,node_commands,node_scenario,node_network,node_whatifrun toneMint
class node_detectors,node_compare,node_sensors,node_validation,node_maps,node_results toneRose
class node_sumo toneIndigo
```

## Components

### Conversational agent

- [Web and CLI](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/app.py): `src/agent/app.py`
- [Request agent](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/agente.py): `src/agent/agente.py`
- [Agent settings](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/configurazione.py): `src/agent/configurazione.py`
- [Road index](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/indice_rete.py): `src/agent/indice_rete.py`
- [Request resolution](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/risolvi.py): `src/agent/risolvi.py`
- [Scenario engine](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/motore.py): `src/agent/motore.py`
- [Simulation interface](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/agent/simula.py): `src/agent/simula.py`

### Twin inputs

- [Twin configuration](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/config.py): `src/dtsumo/inputs/config.py`
- [Input database](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/database.py): `src/dtsumo/inputs/database.py`
- [OD preparation](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/inputs/dayODs.py): `src/dtsumo/inputs/dayODs.py`
- [TAZ zones](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/taz_zones.py): `src/dtsumo/operations/taz_zones.py`
- [Assignment entities](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/modules/entities.py): `src/dtsumo/modules/entities.py`

### Assignment and scenarios

- [Assignment orchestration](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/assignment.py): `src/dtsumo/operations/assignment.py`
- [Iterative assignment](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/marouter_cycle.py): `src/dtsumo/operations/marouter_cycle.py`
- [OD extension](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/od_extension.py): `src/dtsumo/operations/od_extension.py`
- [SUMO tool commands](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/operations/cmd.py): `src/dtsumo/operations/cmd.py`
- [Scenario interpretation](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/scenario.py): `src/dtsumo/whatif/scenario.py`
- [Scenario network](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/network.py): `src/dtsumo/whatif/network.py`
- [What-if runner](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/whatif/run.py): `src/dtsumo/whatif/run.py`

### Analysis and validation

- [Detector processing](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/tools/detectors.py): `src/dtsumo/tools/detectors.py`
- [Scenario comparison](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/compare.py): `src/dtsumo/analysis/compare.py`
- [Sensor analysis](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sensors.py): `src/dtsumo/analysis/sensors.py`
- [Sensor validation](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sensors_validation.py): `src/dtsumo/analysis/sensors_validation.py`
- [Result maps](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/maps.py): `src/dtsumo/analysis/maps.py`
- [SUMO results](https://github.com/irenemarta/macromobilitysumoagent/blob/main/src/dtsumo/analysis/sumoResults.py): `src/dtsumo/analysis/sumoResults.py`

### Other components

- **User**
- **SUMO simulator**
- **CinqueT sensor data**

## Connections

- User → Web and CLI: submits request
- Web and CLI → Request agent: routes interaction (evidence: `src/agent/app.py`)
- Request agent → Agent settings: loads settings (evidence: `src/agent/agente.py`)
- Request agent → Road index: looks up roads (evidence: `src/agent/agente.py`)
- Request agent → Request resolution: validates request (evidence: `src/agent/agente.py`)
- Request agent → Scenario engine: invokes tools (evidence: `src/agent/agente.py`)
- Scenario engine → Scenario interpretation: uses scenario format (evidence: `src/agent/motore.py`)
- Scenario engine → What-if runner: runs scenario (evidence: `src/agent/motore.py`)
- Scenario engine → Twin configuration: reads configuration (evidence: `src/agent/motore.py`)
- Web and CLI → Simulation interface: starts simulation (evidence: `src/agent/app.py`)
- Simulation interface → Scenario engine: coordinates execution (evidence: `src/agent/simula.py`)
- Simulation interface → Scenario comparison: compares results (evidence: `src/agent/simula.py`)
- What-if runner → Scenario interpretation: resolves interventions (evidence: `src/dtsumo/whatif/run.py`)
- What-if runner → Scenario network: builds scenario network (evidence: `src/dtsumo/whatif/run.py`)
- What-if runner → Assignment orchestration: runs assignment (evidence: `src/dtsumo/whatif/run.py`)
- What-if runner → OD extension: extends demand (evidence: `src/dtsumo/whatif/run.py`)
- What-if runner → Detector processing: uses detectors (evidence: `src/dtsumo/whatif/run.py`)
- What-if runner → SUMO simulator: runs simulation (evidence: `src/dtsumo/whatif/run.py`)
- Assignment orchestration → TAZ zones: uses zones (evidence: `src/dtsumo/operations/assignment.py`)
- Assignment orchestration → Iterative assignment: runs cycles (evidence: `src/dtsumo/operations/assignment.py`)
- Assignment orchestration → OD extension: extends OD (evidence: `src/dtsumo/operations/assignment.py`)
- Iterative assignment → SUMO tool commands: invokes tools (evidence: `src/dtsumo/operations/marouter_cycle.py`)
- Iterative assignment → SUMO simulator: simulates rounds (evidence: `src/dtsumo/operations/marouter_cycle.py`)
- TAZ zones → Assignment entities: builds context (evidence: `src/dtsumo/operations/taz_zones.py`)
- OD extension → SUMO tool commands: invokes routing (evidence: `src/dtsumo/operations/od_extension.py`)
- Input database → Twin configuration: uses paths (evidence: `src/dtsumo/inputs/database.py`)
- OD preparation → Twin configuration: uses settings (evidence: `src/dtsumo/inputs/dayODs.py`)
- Scenario comparison → Twin configuration: reads settings (evidence: `src/dtsumo/analysis/compare.py`)
- Sensor validation → Result maps: uses map analysis (evidence: `src/dtsumo/analysis/sensors_validation.py`)
- Sensor validation → Sensor analysis: uses sensor analysis (evidence: `src/dtsumo/analysis/sensors_validation.py`)
- Sensor validation → Detector processing: uses detector data (evidence: `src/dtsumo/analysis/sensors_validation.py`)
- Sensor validation → CinqueT sensor data: validates against
- Result maps → Detector processing: uses detector data (evidence: `src/dtsumo/analysis/maps.py`)
- SUMO results → Twin configuration: uses settings (evidence: `src/dtsumo/analysis/sumoResults.py`)
