# dmau1420/transystem-twins architecture

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

- Interactive diagram: https://gitdiagram.com/dmau1420/transystem-twins
- Repository: https://github.com/dmau1420/transystem-twins

## Overview

TranSystem-Twins is a modular platform for building and evaluating intelligent-transport digital twins. The visible user workflow is to authenticate, explore a map, search for a location, and define map data; the project/scenario and SUMO modules describe the broader workflow of importing an OSM area, building a scenario, simulating it, and analyzing results. The graph combines sampled calls with module references in the source index; some frontend integrations and unsampled backend capabilities are therefore shown only where their ownership is documented.

Main entry points: [`sumo/main.py`](https://github.com/dmau1420/transystem-twins/blob/main/sumo/main.py) (Simulation coordinator), [`frontend/src/App.jsx`](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/App.jsx) (App routes), [`backend/main.py`](https://github.com/dmau1420/transystem-twins/blob/main/backend/main.py) (FastAPI application), [`frontend/src/components/map/MapContainer.jsx`](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/map/MapContainer.jsx) (Map view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Mapping interface"]
  node_app["App routes<br/>[App.jsx]"]
  node_map["Map view<br/>[MapContainer.jsx]"]
  node_mapdata["Map data state<br/>[MapDataContext.jsx]"]
  node_maptools["Map data panel<br/>[MapDataPanel.jsx]"]
  node_search["Location search<br/>[SearchBar.jsx]"]
  node_geocoding["Geocoding<br/>[geocoding.js]"]
  node_projects["Projects panel<br/>[ProjectsPanel.jsx]"]
  node_sidebar["Sidebar<br/>[Sidebar.jsx]"]
end

subgraph group_auth["Authentication"]
  node_authui["Login and registration<br/>[RegisterPage.jsx]"]
  node_authstate["Frontend auth state<br/>[AuthContext.jsx]"]
end

subgraph group_backend["Backend API"]
  node_backendapi["FastAPI application<br/>[main.py]"]
  node_authrouter["Auth routes<br/>[r_auth.py]"]
  node_authservice["Auth service<br/>[auth_service.py]"]
  node_users[("User records<br/>[md_user.py]")]
  node_scenarios["Scenario routes<br/>[r_escenarios.py]"]
  node_pointsrouter["Points routes<br/>[r_points.py]"]
  node_pointsservice[("Points storage<br/>[points_service.py]")]
end

subgraph group_simulation["SUMO workflow"]
  node_osmimport["OSM import<br/>[importacion_osm.py]"]
  node_sumomain["Simulation coordinator<br/>[main.py]"]
  node_datagen["Network and demand data<br/>[data_generators.py]"]
  node_scenario["Scenario network builder"]
  node_simengine["SUMO simulation"]
  node_analyzer["Result analysis<br/>[result_analyzer.py]"]
  node_sumotools["SUMO tools<br/>[sumo_tools.py]"]
end

node_user(("User"))
node_overpass(("Overpass / OSM"))
node_sumo(("SUMO runtime"))

node_user -->|"opens"| node_app
node_app -->|"renders"| node_map
node_app -->|"renders"| node_maptools
node_app -->|"renders"| node_search
node_app -->|"renders"| node_sidebar
node_app -->|"routes to"| node_authui
node_app -->|"provides"| node_authstate
node_map -->|"reads"| node_mapdata
node_map -->|"uses"| node_geocoding
node_search -->|"searches"| node_geocoding
node_search -->|"sets target"| node_mapdata
node_maptools -->|"reads"| node_mapdata
node_maptools -->|"requests data"| node_backendapi
node_sidebar -->|"renders"| node_projects
node_authui -->|"uses"| node_authstate
node_backendapi -->|"registers"| node_authrouter
node_backendapi -->|"registers"| node_scenarios
node_backendapi -->|"registers"| node_pointsrouter
node_authrouter -->|"calls"| node_authservice
node_authservice -->|"queries and writes"| node_users
node_pointsrouter -->|"calls"| node_pointsservice
node_sumomain -.->|"imports OSM"| node_osmimport
node_sumomain -->|"downloads network"| node_overpass
node_sumomain -->|"generates inputs"| node_datagen
node_sumomain -->|"builds network"| node_scenario
node_sumomain -->|"runs"| node_simengine
node_sumomain -->|"processes results"| node_analyzer
node_simengine -->|"drives simulation"| node_sumo
node_simengine -->|"checks output"| node_sumotools
node_sumomain -->|"posts results"| node_backendapi

click node_app "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/App.jsx"
click node_map "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/map/MapContainer.jsx"
click node_mapdata "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/context/MapDataContext.jsx"
click node_maptools "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/MapDataPanel.jsx"
click node_search "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/SearchBar.jsx"
click node_geocoding "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/utils/geocoding.js"
click node_projects "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/dashboard/ProjectsPanel.jsx"
click node_sidebar "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/sidebar/Sidebar.jsx"
click node_authui "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/pages/RegisterPage.jsx"
click node_authstate "https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/context/AuthContext.jsx"
click node_backendapi "https://github.com/dmau1420/transystem-twins/blob/main/backend/main.py"
click node_authrouter "https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_auth.py"
click node_authservice "https://github.com/dmau1420/transystem-twins/blob/main/backend/services/auth_service.py"
click node_users "https://github.com/dmau1420/transystem-twins/blob/main/backend/models/md_user.py"
click node_scenarios "https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_escenarios.py"
click node_pointsrouter "https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_points.py"
click node_pointsservice "https://github.com/dmau1420/transystem-twins/blob/main/backend/services/points_service.py"
click node_osmimport "https://github.com/dmau1420/transystem-twins/blob/main/backend/services/importacion_osm.py"
click node_sumomain "https://github.com/dmau1420/transystem-twins/blob/main/sumo/main.py"
click node_datagen "https://github.com/dmau1420/transystem-twins/blob/main/sumo/data_generators.py"
click node_scenario "https://github.com/dmau1420/transystem-twins/blob/main/sumo/scenario_builder.py"
click node_simengine "https://github.com/dmau1420/transystem-twins/blob/main/sumo/simulation_engine.py"
click node_analyzer "https://github.com/dmau1420/transystem-twins/blob/main/sumo/result_analyzer.py"
click node_sumotools "https://github.com/dmau1420/transystem-twins/blob/main/sumo/sumo_tools.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_app,node_map,node_mapdata,node_maptools,node_search,node_geocoding,node_projects,node_sidebar,node_user toneBlue
class node_authui,node_authstate toneAmber
class node_backendapi,node_authrouter,node_authservice,node_users,node_scenarios,node_pointsrouter,node_pointsservice toneMint
class node_osmimport,node_sumomain,node_datagen,node_scenario,node_simengine,node_analyzer,node_sumotools toneRose
class node_overpass,node_sumo toneIndigo
```

## Components

### Mapping interface

- [App routes](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Map view](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/map/MapContainer.jsx): `frontend/src/components/map/MapContainer.jsx`
- [Map data state](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/context/MapDataContext.jsx): `frontend/src/context/MapDataContext.jsx`
- [Map data panel](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/MapDataPanel.jsx): `frontend/src/components/MapDataPanel.jsx`
- [Location search](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/SearchBar.jsx): `frontend/src/components/SearchBar.jsx`
- [Geocoding](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/utils/geocoding.js): `frontend/src/utils/geocoding.js`
- [Projects panel](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/dashboard/ProjectsPanel.jsx): `frontend/src/components/dashboard/ProjectsPanel.jsx`
- [Sidebar](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/components/sidebar/Sidebar.jsx): `frontend/src/components/sidebar/Sidebar.jsx`

### Authentication

- [Login and registration](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/pages/RegisterPage.jsx): `frontend/src/pages/RegisterPage.jsx`
- [Frontend auth state](https://github.com/dmau1420/transystem-twins/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`

### Backend API

- [FastAPI application](https://github.com/dmau1420/transystem-twins/blob/main/backend/main.py): `backend/main.py`
- [Auth routes](https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_auth.py): `backend/routers/r_auth.py`
- [Auth service](https://github.com/dmau1420/transystem-twins/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [User records](https://github.com/dmau1420/transystem-twins/blob/main/backend/models/md_user.py): `backend/models/md_user.py`
- [Scenario routes](https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_escenarios.py): `backend/routers/r_escenarios.py`
- [Points routes](https://github.com/dmau1420/transystem-twins/blob/main/backend/routers/r_points.py): `backend/routers/r_points.py`
- [Points storage](https://github.com/dmau1420/transystem-twins/blob/main/backend/services/points_service.py): `backend/services/points_service.py`

### SUMO workflow

- [OSM import](https://github.com/dmau1420/transystem-twins/blob/main/backend/services/importacion_osm.py): `backend/services/importacion_osm.py`
- [Simulation coordinator](https://github.com/dmau1420/transystem-twins/blob/main/sumo/main.py): `sumo/main.py`
- [Network and demand data](https://github.com/dmau1420/transystem-twins/blob/main/sumo/data_generators.py): `sumo/data_generators.py`
- [Scenario network builder](https://github.com/dmau1420/transystem-twins/blob/main/sumo/scenario_builder.py): `sumo/scenario_builder.py`
- [SUMO simulation](https://github.com/dmau1420/transystem-twins/blob/main/sumo/simulation_engine.py): `sumo/simulation_engine.py`
- [Result analysis](https://github.com/dmau1420/transystem-twins/blob/main/sumo/result_analyzer.py): `sumo/result_analyzer.py`
- [SUMO tools](https://github.com/dmau1420/transystem-twins/blob/main/sumo/sumo_tools.py): `sumo/sumo_tools.py`

### Other components

- **User**
- **Overpass / OSM**
- **SUMO runtime**

## Connections

- User → App routes: opens (evidence: `frontend/src/App.jsx`)
- App routes → Map view: renders (evidence: `frontend/src/App.jsx`)
- App routes → Map data panel: renders (evidence: `frontend/src/App.jsx`)
- App routes → Location search: renders (evidence: `frontend/src/App.jsx`)
- App routes → Sidebar: renders (evidence: `frontend/src/App.jsx`)
- App routes → Login and registration: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Frontend auth state: provides (evidence: `frontend/src/App.jsx`)
- Map view → Map data state: reads (evidence: `frontend/src/components/map/MapContainer.jsx`)
- Map view → Geocoding: uses (evidence: `frontend/src/components/map/MapContainer.jsx`)
- Location search → Geocoding: searches (evidence: `frontend/src/components/SearchBar.jsx`)
- Location search → Map data state: sets target (evidence: `frontend/src/components/SearchBar.jsx`)
- Map data panel → Map data state: reads (evidence: `frontend/src/components/MapDataPanel.jsx`)
- Map data panel → FastAPI application: requests data (evidence: `frontend/src/components/MapDataPanel.jsx`)
- Sidebar → Projects panel: renders (evidence: `frontend/src/components/sidebar/Sidebar.jsx`)
- Login and registration → Frontend auth state: uses (evidence: `frontend/src/pages/RegisterPage.jsx`)
- FastAPI application → Auth routes: registers (evidence: `backend/main.py`)
- FastAPI application → Scenario routes: registers (evidence: `backend/main.py`)
- FastAPI application → Points routes: registers (evidence: `backend/main.py`)
- Auth routes → Auth service: calls (evidence: `backend/routers/r_auth.py`)
- Auth service → User records: queries and writes (evidence: `backend/services/auth_service.py`)
- Points routes → Points storage: calls (evidence: `backend/routers/r_points.py`)
- Simulation coordinator → OSM import: imports OSM
- Simulation coordinator → Overpass / OSM: downloads network (evidence: `sumo/main.py`)
- Simulation coordinator → Network and demand data: generates inputs (evidence: `sumo/main.py`)
- Simulation coordinator → Scenario network builder: builds network (evidence: `sumo/main.py`)
- Simulation coordinator → SUMO simulation: runs (evidence: `sumo/main.py`)
- Simulation coordinator → Result analysis: processes results (evidence: `sumo/main.py`)
- SUMO simulation → SUMO runtime: drives simulation (evidence: `sumo/simulation_engine.py`)
- SUMO simulation → SUMO tools: checks output (evidence: `sumo/simulation_engine.py`)
- Simulation coordinator → FastAPI application: posts results (evidence: `sumo/main.py`)
