# iordjn/tareek architecture

> Architecture diagram of the GitHub repository iordjn/tareek, 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/iordjn/tareek
- Repository: https://github.com/iordjn/tareek

## Overview

TAREEK turns county-based configuration into a MATSim travel-demand simulation and evaluates it against traffic counts. Its main workflow is region setup, data acquisition, network construction, demand and plan generation, simulation, and validation. The graph also preserves documented configuration-wizard, transit, and freight capabilities. The README establishes the overall stages; SOURCE INDEX references support several module relationships. Unsampled implementations are represented by their exact tree paths, with relationships omitted where their caller or data flow is not evidenced.

Main entry points: [`run_experiment.py`](https://github.com/iordjn/tareek/blob/main/run_experiment.py) (Experiment runner), [`models/plan_generator.py`](https://github.com/iordjn/tareek/blob/main/models/plan_generator.py) (Work plans), [`models/plan_generator_nonwork.py`](https://github.com/iordjn/tareek/blob/main/models/plan_generator_nonwork.py) (Non-work plans), [`data_sources/survey_manager.py`](https://github.com/iordjn/tareek/blob/main/data_sources/survey_manager.py) (Survey ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup_data["Setup and data"]
  node_config["Region config<br/>[config.py]"]
  node_runner["Experiment runner<br/>[run_experiment.py]"]
  node_survey["Survey ingestion<br/>[survey_manager.py]"]
  node_survey_sources["Survey sources"]
  node_gtfs["GTFS feeds<br/>[gtfs_manager.py]"]
  node_storage[("DuckDB data store<br/>[duckdb_manager.py]")]
end

subgraph group_demand["Travel demand"]
  node_budget["Demand budget<br/>[demand_budget.py]"]
  node_chains_time["Chains and timing<br/>[chains.py]"]
  node_locations["Home and work locations<br/>[home_locs_v2.py]"]
  node_poi["Activity destinations<br/>[poi_manager.py]"]
  node_mode_choice["Mode choice<br/>[mode_choice.py]"]
  node_work_plans["Work plans<br/>[plan_generator.py]"]
  node_nonwork_plans["Non-work plans"]
  node_freight["Freight demand"]
end

subgraph group_simulation["MATSim simulation"]
  node_network["Road and transit network"]
  node_matsim_config["MATSim configuration<br/>[config_manager.py]"]
  node_simulator["MATSim runner<br/>[runner.py]"]
end

subgraph group_evaluation["Validation and results"]
  node_counts["Traffic counts"]
  node_evaluator["Simulation evaluator<br/>[evaluator.py]"]
end

subgraph group_interface["Configuration interface"]
  node_wizard["Config Wizard<br/>[main.py]"]
  node_frontend["Wizard interface<br/>[app.js]"]
end

node_user(("Region researcher"))

node_user -->|"selects region"| node_config
node_user -->|"configures region"| node_wizard
node_wizard -->|"exports config"| node_config
node_config -->|"configures run"| node_runner
node_runner -->|"loads surveys"| node_survey
node_survey -->|"selects sources"| node_survey_sources
node_survey_sources -->|"saves trips"| node_storage
node_runner -->|"builds network"| node_network
node_network -->|"loads transit feeds"| node_gtfs
node_survey -->|"informs demand"| node_budget
node_budget -->|"sets demand"| node_work_plans
node_budget -->|"sets demand"| node_nonwork_plans
node_work_plans -->|"uses chains and timing"| node_chains_time
node_work_plans -->|"assigns locations"| node_locations
node_work_plans -->|"assigns destinations"| node_poi
node_work_plans -->|"chooses modes"| node_mode_choice
node_nonwork_plans -->|"uses chains and timing"| node_chains_time
node_nonwork_plans -->|"assigns destinations"| node_poi
node_nonwork_plans -->|"chooses modes"| node_mode_choice
node_runner -->|"generates plans"| node_work_plans
node_runner -->|"generates plans"| node_nonwork_plans
node_runner -.->|"estimates freight"| node_freight
node_runner -->|"prepares simulation"| node_matsim_config
node_runner -->|"runs simulation"| node_simulator
node_simulator -->|"evaluates output"| node_evaluator
node_counts -->|"provides observations"| node_evaluator
node_runner -->|"compares traffic counts"| node_counts
node_frontend -.->|"drives wizard"| node_wizard

click node_config "https://github.com/iordjn/tareek/blob/main/config/config.py"
click node_runner "https://github.com/iordjn/tareek/blob/main/run_experiment.py"
click node_survey "https://github.com/iordjn/tareek/blob/main/data_sources/survey_manager.py"
click node_survey_sources "https://github.com/iordjn/tareek/blob/main/data_sources/base_survey_trip.py"
click node_gtfs "https://github.com/iordjn/tareek/blob/main/data_sources/gtfs_manager.py"
click node_storage "https://github.com/iordjn/tareek/blob/main/utils/duckdb_manager.py"
click node_network "https://github.com/iordjn/tareek/blob/main/matsim/network_generator.py"
click node_budget "https://github.com/iordjn/tareek/blob/main/models/demand_budget.py"
click node_chains_time "https://github.com/iordjn/tareek/blob/main/models/chains.py"
click node_locations "https://github.com/iordjn/tareek/blob/main/models/home_locs_v2.py"
click node_poi "https://github.com/iordjn/tareek/blob/main/models/poi_manager.py"
click node_mode_choice "https://github.com/iordjn/tareek/blob/main/models/mode_choice.py"
click node_work_plans "https://github.com/iordjn/tareek/blob/main/models/plan_generator.py"
click node_nonwork_plans "https://github.com/iordjn/tareek/blob/main/models/plan_generator_nonwork.py"
click node_freight "https://github.com/iordjn/tareek/blob/main/estimators/freight_estimator.py"
click node_matsim_config "https://github.com/iordjn/tareek/blob/main/matsim/config_manager.py"
click node_simulator "https://github.com/iordjn/tareek/blob/main/matsim/runner.py"
click node_counts "https://github.com/iordjn/tareek/blob/main/matsim/counts_generator.py"
click node_evaluator "https://github.com/iordjn/tareek/blob/main/matsim/evaluator.py"
click node_wizard "https://github.com/iordjn/tareek/blob/main/webapp/backend/main.py"
click node_frontend "https://github.com/iordjn/tareek/blob/main/webapp/frontend/js/app.js"

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_config,node_runner,node_survey,node_survey_sources,node_gtfs,node_storage toneBlue
class node_budget,node_chains_time,node_locations,node_poi,node_mode_choice,node_work_plans,node_nonwork_plans,node_freight toneAmber
class node_network,node_matsim_config,node_simulator toneMint
class node_counts,node_evaluator toneRose
class node_wizard,node_frontend,node_user toneIndigo
```

## Components

### Setup and data

- [Region config](https://github.com/iordjn/tareek/blob/main/config/config.py): `config/config.py`
- [Experiment runner](https://github.com/iordjn/tareek/blob/main/run_experiment.py): `run_experiment.py`
- [Survey ingestion](https://github.com/iordjn/tareek/blob/main/data_sources/survey_manager.py): `data_sources/survey_manager.py`
- [Survey sources](https://github.com/iordjn/tareek/blob/main/data_sources/base_survey_trip.py): `data_sources/base_survey_trip.py`
- [GTFS feeds](https://github.com/iordjn/tareek/blob/main/data_sources/gtfs_manager.py): `data_sources/gtfs_manager.py`
- [DuckDB data store](https://github.com/iordjn/tareek/blob/main/utils/duckdb_manager.py): `utils/duckdb_manager.py`

### Travel demand

- [Demand budget](https://github.com/iordjn/tareek/blob/main/models/demand_budget.py): `models/demand_budget.py`
- [Chains and timing](https://github.com/iordjn/tareek/blob/main/models/chains.py): `models/chains.py`
- [Home and work locations](https://github.com/iordjn/tareek/blob/main/models/home_locs_v2.py): `models/home_locs_v2.py`
- [Activity destinations](https://github.com/iordjn/tareek/blob/main/models/poi_manager.py): `models/poi_manager.py`
- [Mode choice](https://github.com/iordjn/tareek/blob/main/models/mode_choice.py): `models/mode_choice.py`
- [Work plans](https://github.com/iordjn/tareek/blob/main/models/plan_generator.py): `models/plan_generator.py`
- [Non-work plans](https://github.com/iordjn/tareek/blob/main/models/plan_generator_nonwork.py): `models/plan_generator_nonwork.py`
- [Freight demand](https://github.com/iordjn/tareek/blob/main/estimators/freight_estimator.py): `estimators/freight_estimator.py`

### MATSim simulation

- [Road and transit network](https://github.com/iordjn/tareek/blob/main/matsim/network_generator.py): `matsim/network_generator.py`
- [MATSim configuration](https://github.com/iordjn/tareek/blob/main/matsim/config_manager.py): `matsim/config_manager.py`
- [MATSim runner](https://github.com/iordjn/tareek/blob/main/matsim/runner.py): `matsim/runner.py`

### Validation and results

- [Traffic counts](https://github.com/iordjn/tareek/blob/main/matsim/counts_generator.py): `matsim/counts_generator.py`
- [Simulation evaluator](https://github.com/iordjn/tareek/blob/main/matsim/evaluator.py): `matsim/evaluator.py`

### Configuration interface

- [Config Wizard](https://github.com/iordjn/tareek/blob/main/webapp/backend/main.py): `webapp/backend/main.py`
- [Wizard interface](https://github.com/iordjn/tareek/blob/main/webapp/frontend/js/app.js): `webapp/frontend/js/app.js`

### Other components

- **Region researcher**

## Connections

- Region researcher → Region config: selects region (evidence: `README.md`)
- Region researcher → Config Wizard: configures region (evidence: `README.md`)
- Config Wizard → Region config: exports config (evidence: `README.md`)
- Region config → Experiment runner: configures run (evidence: `README.md`)
- Experiment runner → Survey ingestion: loads surveys (evidence: `run_experiment.py`)
- Survey ingestion → Survey sources: selects sources (evidence: `data_sources/survey_manager.py`)
- Survey sources → DuckDB data store: saves trips (evidence: `data_sources/base_survey_trip.py`)
- Experiment runner → Road and transit network: builds network (evidence: `run_experiment.py`)
- Road and transit network → GTFS feeds: loads transit feeds (evidence: `matsim/network_generator.py`)
- Survey ingestion → Demand budget: informs demand (evidence: `models/demand_budget.py`)
- Demand budget → Work plans: sets demand (evidence: `models/plan_generator.py`)
- Demand budget → Non-work plans: sets demand (evidence: `models/plan_generator_nonwork.py`)
- Work plans → Chains and timing: uses chains and timing (evidence: `models/plan_generator.py`)
- Work plans → Home and work locations: assigns locations (evidence: `models/plan_generator.py`)
- Work plans → Activity destinations: assigns destinations (evidence: `models/plan_generator.py`)
- Work plans → Mode choice: chooses modes (evidence: `models/plan_generator.py`)
- Non-work plans → Chains and timing: uses chains and timing (evidence: `models/plan_generator_nonwork.py`)
- Non-work plans → Activity destinations: assigns destinations (evidence: `models/plan_generator_nonwork.py`)
- Non-work plans → Mode choice: chooses modes (evidence: `models/plan_generator_nonwork.py`)
- Experiment runner → Work plans: generates plans (evidence: `run_experiment.py`)
- Experiment runner → Non-work plans: generates plans (evidence: `run_experiment.py`)
- Experiment runner → Freight demand: estimates freight (evidence: `run_experiment.py`)
- Experiment runner → MATSim configuration: prepares simulation (evidence: `run_experiment.py`)
- Experiment runner → MATSim runner: runs simulation (evidence: `run_experiment.py`)
- MATSim runner → Simulation evaluator: evaluates output (evidence: `README.md`)
- Traffic counts → Simulation evaluator: provides observations (evidence: `README.md`)
- Experiment runner → Traffic counts: compares traffic counts (evidence: `run_experiment.py`)
- Wizard interface → Config Wizard: drives wizard
