# taotlema/valmistada architecture

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

- Interactive diagram: https://gitdiagram.com/taotlema/valmistada
- Repository: https://github.com/taotlema/valmistada

## Overview

Valmistada is a PyQt6 transit-ridership simulation research application. Users choose a generation model and configure inputs, then run a simulated MUNI year; the app loads and processes GTFS, builds a network, simulates ridership, aggregates daily counts into trial results, and presents or exports outputs. The README also describes four generation models and modifier data. Connections reflect excerpts, SOURCE INDEX references, and README statements; unsampled subsystem details and the benchmarking implementation are not inferred.

Main entry points: [`SD_Game/game_world/core/simulation_engine.py`](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/core/simulation_engine.py) (Simulation engine), [`SD_Game/app_controller/app.py`](https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/app.py) (App controller), [`SD_Game/data/processors/aggregator.py`](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/aggregator.py) (Ridership aggregation), [`SD_Game/ui/screens/start_screen.py`](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/start_screen.py) (Start screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_app["App controller<br/>[app.py]"]
  node_bus["Event bus<br/>[event_bus.py]"]
  node_screens["Screen navigation<br/>[screen_manager.py]"]
  node_start["Start screen<br/>[start_screen.py]"]
  node_input["Input screen<br/>[input_screen.py]"]
  node_worldscreen["Simulation screen"]
  node_output["Output screen<br/>[output_screen.py]"]
  node_dictionary["Dictionary screen"]
end

subgraph group_data["Data preparation"]
  node_gtfsloader["GTFS loader<br/>[gtfs_loader.py]"]
  node_gtfsmodels["GTFS models<br/>[gtfs_models.py]"]
  node_validator["Input validation<br/>[data_validator.py]"]
  node_processor["GTFS processor<br/>[gtfs_processor.py]"]
  node_modifiers["Modifier loading<br/>[modifier_loader.py]"]
  node_outputloader["Trial loading<br/>[output_loader.py]"]
  node_export["Result export<br/>[export_manager.py]"]
  node_aggregator["Ridership aggregation<br/>[aggregator.py]"]
  node_records["Trial records<br/>[output_models.py]"]
end

subgraph group_simulation["Simulation runtime"]
  node_engine["Simulation engine"]
  node_scheduler["Scheduling"]
  node_modifier["Demand modifiers<br/>[modifier_system.py]"]
  node_ridership["Ridership models"]
  node_deterministic["Deterministic model"]
  node_hifi["High-fidelity model"]
  node_rb2["Rule-based v2"]
end

subgraph group_world["Transit world"]
  node_graph["Network builder<br/>[graph_builder.py]"]
  node_map["Map rendering"]
  node_entities["Transit entities<br/>[route.py]"]
end

node_user(("Research user"))

node_user -->|"chooses workflow"| node_start
node_app -->|"registers screens"| node_screens
node_app -->|"loads feed"| node_gtfsloader
node_app -->|"validates feed"| node_validator
node_app -->|"indexes feed"| node_processor
node_gtfsloader -->|"creates models"| node_gtfsmodels
node_processor -->|"indexes records"| node_gtfsmodels
node_start -->|"navigates"| node_screens
node_input -->|"navigates"| node_screens
node_start -->|"subscribes events"| node_bus
node_worldscreen -->|"starts simulation"| node_engine
node_worldscreen -->|"subscribes events"| node_bus
node_engine -->|"publishes events"| node_bus
node_engine -->|"builds network"| node_graph
node_engine -->|"sets renderer"| node_map
node_engine -->|"creates world entities"| node_entities
node_graph -->|"reads route data"| node_processor
node_graph -->|"builds routes"| node_entities
node_map -->|"renders network"| node_entities
node_engine -->|"dispatches scheduling"| node_scheduler
node_engine -->|"applies modifiers"| node_modifier
node_engine -->|"selects model"| node_ridership
node_engine -->|"selects model"| node_deterministic
node_engine -->|"selects model"| node_hifi
node_engine -->|"selects model"| node_rb2
node_engine -->|"flushes daily counts"| node_aggregator
node_ridership -->|"records boardings"| node_aggregator
node_deterministic -->|"records boardings"| node_aggregator
node_rb2 -->|"records boardings"| node_aggregator
node_aggregator -->|"creates trial results"| node_records
node_app -->|"exports completed trial"| node_export
node_app -->|"refreshes results"| node_output
node_output -.->|"loads saved trials"| node_outputloader
node_app -.->|"loads modifiers"| node_modifiers

click node_app "https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/app.py"
click node_bus "https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/event_bus.py"
click node_screens "https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/screen_manager.py"
click node_start "https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/start_screen.py"
click node_input "https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/input_screen.py"
click node_worldscreen "https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/game_world_screen.py"
click node_output "https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/output_screen.py"
click node_dictionary "https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/dictionary_screen.py"
click node_gtfsloader "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/gtfs_loader.py"
click node_gtfsmodels "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/models/gtfs_models.py"
click node_validator "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/data_validator.py"
click node_processor "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/gtfs_processor.py"
click node_modifiers "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/modifier_loader.py"
click node_outputloader "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/output_loader.py"
click node_export "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/storage/export_manager.py"
click node_engine "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/core/simulation_engine.py"
click node_scheduler "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/scheduling_system.py"
click node_modifier "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/modifier_system.py"
click node_ridership "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system.py"
click node_deterministic "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_deterministic.py"
click node_hifi "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_hifi.py"
click node_rb2 "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_rb2.py"
click node_graph "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/map/graph_builder.py"
click node_map "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/map/renderer_adapter.py"
click node_entities "https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/entities/route.py"
click node_aggregator "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/aggregator.py"
click node_records "https://github.com/taotlema/valmistada/blob/main/SD_Game/data/models/output_models.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_bus,node_screens,node_start,node_input,node_worldscreen,node_output,node_dictionary,node_user toneBlue
class node_gtfsloader,node_gtfsmodels,node_validator,node_processor,node_modifiers,node_outputloader,node_export,node_aggregator,node_records toneAmber
class node_engine,node_scheduler,node_modifier,node_ridership,node_deterministic,node_hifi,node_rb2 toneMint
class node_graph,node_map,node_entities toneRose
```

## Components

### Desktop interface

- [App controller](https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/app.py): `SD_Game/app_controller/app.py`
- [Event bus](https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/event_bus.py): `SD_Game/app_controller/event_bus.py`
- [Screen navigation](https://github.com/taotlema/valmistada/blob/main/SD_Game/app_controller/screen_manager.py): `SD_Game/app_controller/screen_manager.py`
- [Start screen](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/start_screen.py): `SD_Game/ui/screens/start_screen.py`
- [Input screen](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/input_screen.py): `SD_Game/ui/screens/input_screen.py`
- [Simulation screen](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/game_world_screen.py): `SD_Game/ui/screens/game_world_screen.py`
- [Output screen](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/output_screen.py): `SD_Game/ui/screens/output_screen.py`
- [Dictionary screen](https://github.com/taotlema/valmistada/blob/main/SD_Game/ui/screens/dictionary_screen.py): `SD_Game/ui/screens/dictionary_screen.py`

### Data preparation

- [GTFS loader](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/gtfs_loader.py): `SD_Game/data/loaders/gtfs_loader.py`
- [GTFS models](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/models/gtfs_models.py): `SD_Game/data/models/gtfs_models.py`
- [Input validation](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/data_validator.py): `SD_Game/data/processors/data_validator.py`
- [GTFS processor](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/gtfs_processor.py): `SD_Game/data/processors/gtfs_processor.py`
- [Modifier loading](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/modifier_loader.py): `SD_Game/data/loaders/modifier_loader.py`
- [Trial loading](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/loaders/output_loader.py): `SD_Game/data/loaders/output_loader.py`
- [Result export](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/storage/export_manager.py): `SD_Game/data/storage/export_manager.py`
- [Ridership aggregation](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/processors/aggregator.py): `SD_Game/data/processors/aggregator.py`
- [Trial records](https://github.com/taotlema/valmistada/blob/main/SD_Game/data/models/output_models.py): `SD_Game/data/models/output_models.py`

### Simulation runtime

- [Simulation engine](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/core/simulation_engine.py): `SD_Game/game_world/core/simulation_engine.py`
- [Scheduling](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/scheduling_system.py): `SD_Game/game_world/systems/scheduling_system.py`
- [Demand modifiers](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/modifier_system.py): `SD_Game/game_world/systems/modifier_system.py`
- [Ridership models](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system.py): `SD_Game/game_world/systems/ridership_system.py`
- [Deterministic model](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_deterministic.py): `SD_Game/game_world/systems/ridership_system_deterministic.py`
- [High-fidelity model](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_hifi.py): `SD_Game/game_world/systems/ridership_system_hifi.py`
- [Rule-based v2](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/systems/ridership_system_rb2.py): `SD_Game/game_world/systems/ridership_system_rb2.py`

### Transit world

- [Network builder](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/map/graph_builder.py): `SD_Game/game_world/map/graph_builder.py`
- [Map rendering](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/map/renderer_adapter.py): `SD_Game/game_world/map/renderer_adapter.py`
- [Transit entities](https://github.com/taotlema/valmistada/blob/main/SD_Game/game_world/entities/route.py): `SD_Game/game_world/entities/route.py`

### Other components

- **Research user**

## Connections

- Research user → Start screen: chooses workflow
- App controller → Screen navigation: registers screens (evidence: `SD_Game/app_controller/app.py`)
- App controller → GTFS loader: loads feed (evidence: `SD_Game/app_controller/app.py`)
- App controller → Input validation: validates feed (evidence: `SD_Game/app_controller/app.py`)
- App controller → GTFS processor: indexes feed (evidence: `SD_Game/app_controller/app.py`)
- GTFS loader → GTFS models: creates models (evidence: `SD_Game/data/loaders/gtfs_loader.py`)
- GTFS processor → GTFS models: indexes records (evidence: `SD_Game/data/processors/gtfs_processor.py`)
- Start screen → Screen navigation: navigates (evidence: `SD_Game/ui/screens/start_screen.py`)
- Input screen → Screen navigation: navigates (evidence: `SD_Game/ui/screens/input_screen.py`)
- Start screen → Event bus: subscribes events (evidence: `SD_Game/ui/screens/start_screen.py`)
- Simulation screen → Simulation engine: starts simulation (evidence: `SD_Game/ui/screens/game_world_screen.py`)
- Simulation screen → Event bus: subscribes events (evidence: `SD_Game/ui/screens/game_world_screen.py`)
- Simulation engine → Event bus: publishes events (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Network builder: builds network (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Map rendering: sets renderer (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Transit entities: creates world entities (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Network builder → GTFS processor: reads route data (evidence: `SD_Game/game_world/map/graph_builder.py`)
- Network builder → Transit entities: builds routes (evidence: `SD_Game/game_world/map/graph_builder.py`)
- Map rendering → Transit entities: renders network (evidence: `SD_Game/game_world/map/renderer_adapter.py`)
- Simulation engine → Scheduling: dispatches scheduling (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Demand modifiers: applies modifiers (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Ridership models: selects model (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Deterministic model: selects model (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → High-fidelity model: selects model (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Rule-based v2: selects model (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Simulation engine → Ridership aggregation: flushes daily counts (evidence: `SD_Game/game_world/core/simulation_engine.py`)
- Ridership models → Ridership aggregation: records boardings (evidence: `SD_Game/game_world/systems/ridership_system.py`)
- Deterministic model → Ridership aggregation: records boardings (evidence: `SD_Game/game_world/systems/ridership_system_deterministic.py`)
- Rule-based v2 → Ridership aggregation: records boardings (evidence: `SD_Game/game_world/systems/ridership_system_rb2.py`)
- Ridership aggregation → Trial records: creates trial results (evidence: `SD_Game/data/processors/aggregator.py`)
- App controller → Result export: exports completed trial (evidence: `SD_Game/app_controller/app.py`)
- App controller → Output screen: refreshes results (evidence: `SD_Game/app_controller/app.py`)
- Output screen → Trial loading: loads saved trials
- App controller → Modifier loading: loads modifiers (evidence: `SD_Game/app_controller/app.py`)