# jalal1/tareek architecture

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

## Overview

TAREEK turns county-level configuration into regional MATSim travel simulations and validation reports. The principal workflow is configuration → open-data acquisition → network construction → synthetic demand and daily plans → MATSim execution → traffic-count evaluation. Survey processing, spatial/activity models, persistent data, transit availability, freight analysis, and the configuration web app are distinct capabilities. Pipeline links are based on README documentation and SOURCE INDEX references; unsampled implementations are represented only at supported directory or module paths.

Main entry points: [`run_experiment.py`](https://github.com/jalal1/tareek/blob/main/run_experiment.py) (Experiment Runner), [`models/plan_generator.py`](https://github.com/jalal1/tareek/blob/main/models/plan_generator.py) (Activity Plans), [`data_sources/survey_manager.py`](https://github.com/jalal1/tareek/blob/main/data_sources/survey_manager.py) (Survey ETL), [`matsim/network_generator.py`](https://github.com/jalal1/tareek/blob/main/matsim/network_generator.py) (Road and Transit Network)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Configuration"]
  node_wizard["Config Wizard<br/>[app.js]"]
  node_web_backend["Wizard Backend<br/>[main.py]"]
  node_config["Region Config<br/>[config.py]"]
  node_run["Experiment Runner<br/>[run_experiment.py]"]
end

subgraph group_data["Data and Network"]
  node_surveys["Survey ETL<br/>[survey_manager.py]"]
  node_sources["Census and OD Data"]
  node_poi["POI Locations<br/>[poi_manager.py]"]
  node_gtfs["GTFS Feeds<br/>[gtfs_manager.py]"]
  node_network["Road and Transit Network"]
  node_store[("DuckDB Data Store<br/>[duckdb_manager.py]")]
end

subgraph group_demand["Travel Demand"]
  node_budget["Demand Budget<br/>[demand_budget.py]"]
  node_plans["Activity Plans<br/>[plan_generator.py]"]
  node_nonwork["Nonwork Demand"]
  node_mode["Mode Choice<br/>[mode_choice.py]"]
end

subgraph group_simulation["Simulation and Evaluation"]
  node_matsim["MATSim Run<br/>[runner.py]"]
  node_counts["Traffic Counts"]
  node_evaluation["Validation and Reports<br/>[evaluator.py]"]
end

subgraph group_extensions["Extensions"]
  node_freight["Freight Modeling"]
end

node_user(("Modeler"))
node_transit_service["Transit Feed Catalog"]
node_open_data["Open Data Services"]
node_matsim_engine["MATSim Engine"]

node_user -->|"configures region"| node_wizard
node_wizard -.->|"submits settings"| node_web_backend
node_web_backend -->|"exports config"| node_config
node_user -->|"selects counties"| node_config
node_config -->|"starts experiment"| node_run
node_run -->|"loads surveys"| node_surveys
node_run -->|"gets regional data"| node_sources
node_run -->|"builds network"| node_network
node_run -->|"generates plans"| node_plans
node_run -->|"generates demand"| node_nonwork
node_run -->|"runs simulation"| node_matsim
node_run -->|"evaluates run"| node_evaluation
node_surveys -->|"saves survey data"| node_store
node_poi -->|"reads and writes"| node_store
node_gtfs -->|"discovers feeds"| node_transit_service
node_gtfs -->|"loads feed data"| node_store
node_network -->|"uses transit feeds"| node_gtfs
node_network -->|"downloads road data"| node_open_data
node_sources -->|"fetches census data"| node_open_data
node_plans -->|"uses travel patterns"| node_surveys
node_plans -->|"assigns locations"| node_poi
node_plans -->|"chooses modes"| node_mode
node_plans -->|"uses demand budget"| node_budget
node_nonwork -->|"uses survey patterns"| node_surveys
node_matsim -->|"executes simulation"| node_matsim_engine
node_evaluation -->|"compares counts"| node_counts
node_run -.->|"optional analysis"| node_freight

click node_wizard "https://github.com/jalal1/tareek/blob/main/webapp/frontend/js/app.js"
click node_web_backend "https://github.com/jalal1/tareek/blob/main/webapp/backend/main.py"
click node_config "https://github.com/jalal1/tareek/blob/main/config/config.py"
click node_run "https://github.com/jalal1/tareek/blob/main/run_experiment.py"
click node_surveys "https://github.com/jalal1/tareek/blob/main/data_sources/survey_manager.py"
click node_sources "https://github.com/jalal1/tareek/tree/main/data_sources"
click node_poi "https://github.com/jalal1/tareek/blob/main/models/poi_manager.py"
click node_gtfs "https://github.com/jalal1/tareek/blob/main/data_sources/gtfs_manager.py"
click node_network "https://github.com/jalal1/tareek/blob/main/matsim/network_generator.py"
click node_store "https://github.com/jalal1/tareek/blob/main/utils/duckdb_manager.py"
click node_budget "https://github.com/jalal1/tareek/blob/main/models/demand_budget.py"
click node_plans "https://github.com/jalal1/tareek/blob/main/models/plan_generator.py"
click node_nonwork "https://github.com/jalal1/tareek/blob/main/models/plan_generator_nonwork.py"
click node_mode "https://github.com/jalal1/tareek/blob/main/models/mode_choice.py"
click node_freight "https://github.com/jalal1/tareek/blob/main/estimators/freight_estimator.py"
click node_matsim "https://github.com/jalal1/tareek/blob/main/matsim/runner.py"
click node_counts "https://github.com/jalal1/tareek/blob/main/matsim/counts_generator.py"
click node_evaluation "https://github.com/jalal1/tareek/blob/main/matsim/evaluator.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_wizard,node_web_backend,node_config,node_run toneBlue
class node_surveys,node_sources,node_poi,node_gtfs,node_network,node_store toneAmber
class node_budget,node_plans,node_nonwork,node_mode toneMint
class node_matsim,node_counts,node_evaluation toneRose
class node_freight,node_user,node_transit_service,node_open_data,node_matsim_engine toneIndigo
```

## Components

### Configuration

- [Config Wizard](https://github.com/jalal1/tareek/blob/main/webapp/frontend/js/app.js): `webapp/frontend/js/app.js`
- [Wizard Backend](https://github.com/jalal1/tareek/blob/main/webapp/backend/main.py): `webapp/backend/main.py`
- [Region Config](https://github.com/jalal1/tareek/blob/main/config/config.py): `config/config.py`
- [Experiment Runner](https://github.com/jalal1/tareek/blob/main/run_experiment.py): `run_experiment.py`

### Data and Network

- [Survey ETL](https://github.com/jalal1/tareek/blob/main/data_sources/survey_manager.py): `data_sources/survey_manager.py`
- [Census and OD Data](https://github.com/jalal1/tareek/tree/main/data_sources): `data_sources`
- [POI Locations](https://github.com/jalal1/tareek/blob/main/models/poi_manager.py): `models/poi_manager.py`
- [GTFS Feeds](https://github.com/jalal1/tareek/blob/main/data_sources/gtfs_manager.py): `data_sources/gtfs_manager.py`
- [Road and Transit Network](https://github.com/jalal1/tareek/blob/main/matsim/network_generator.py): `matsim/network_generator.py`
- [DuckDB Data Store](https://github.com/jalal1/tareek/blob/main/utils/duckdb_manager.py): `utils/duckdb_manager.py`

### Travel Demand

- [Demand Budget](https://github.com/jalal1/tareek/blob/main/models/demand_budget.py): `models/demand_budget.py`
- [Activity Plans](https://github.com/jalal1/tareek/blob/main/models/plan_generator.py): `models/plan_generator.py`
- [Nonwork Demand](https://github.com/jalal1/tareek/blob/main/models/plan_generator_nonwork.py): `models/plan_generator_nonwork.py`
- [Mode Choice](https://github.com/jalal1/tareek/blob/main/models/mode_choice.py): `models/mode_choice.py`

### Simulation and Evaluation

- [MATSim Run](https://github.com/jalal1/tareek/blob/main/matsim/runner.py): `matsim/runner.py`
- [Traffic Counts](https://github.com/jalal1/tareek/blob/main/matsim/counts_generator.py): `matsim/counts_generator.py`
- [Validation and Reports](https://github.com/jalal1/tareek/blob/main/matsim/evaluator.py): `matsim/evaluator.py`

### Extensions

- [Freight Modeling](https://github.com/jalal1/tareek/blob/main/estimators/freight_estimator.py): `estimators/freight_estimator.py`

### Other components

- **Modeler**
- **Transit Feed Catalog**
- **Open Data Services**
- **MATSim Engine**

## Connections

- Modeler → Config Wizard: configures region (evidence: `README.md`)
- Config Wizard → Wizard Backend: submits settings
- Wizard Backend → Region Config: exports config (evidence: `README.md`)
- Modeler → Region Config: selects counties (evidence: `README.md`)
- Region Config → Experiment Runner: starts experiment (evidence: `README.md`)
- Experiment Runner → Survey ETL: loads surveys (evidence: `run_experiment.py`)
- Experiment Runner → Census and OD Data: gets regional data (evidence: `README.md`)
- Experiment Runner → Road and Transit Network: builds network (evidence: `run_experiment.py`)
- Experiment Runner → Activity Plans: generates plans (evidence: `run_experiment.py`)
- Experiment Runner → Nonwork Demand: generates demand (evidence: `run_experiment.py`)
- Experiment Runner → MATSim Run: runs simulation (evidence: `run_experiment.py`)
- Experiment Runner → Validation and Reports: evaluates run (evidence: `run_experiment.py`)
- Survey ETL → DuckDB Data Store: saves survey data
- POI Locations → DuckDB Data Store: reads and writes (evidence: `models/poi_manager.py`)
- GTFS Feeds → Transit Feed Catalog: discovers feeds (evidence: `data_sources/gtfs_manager.py`)
- GTFS Feeds → DuckDB Data Store: loads feed data (evidence: `data_sources/gtfs_manager.py`)
- Road and Transit Network → GTFS Feeds: uses transit feeds (evidence: `matsim/network_generator.py`)
- Road and Transit Network → Open Data Services: downloads road data (evidence: `README.md`)
- Census and OD Data → Open Data Services: fetches census data (evidence: `README.md`)
- Activity Plans → Survey ETL: uses travel patterns (evidence: `models/plan_generator.py`)
- Activity Plans → POI Locations: assigns locations (evidence: `models/plan_generator.py`)
- Activity Plans → Mode Choice: chooses modes (evidence: `models/plan_generator.py`)
- Activity Plans → Demand Budget: uses demand budget (evidence: `models/demand_budget.py`)
- Nonwork Demand → Survey ETL: uses survey patterns (evidence: `models/plan_generator_nonwork.py`)
- MATSim Run → MATSim Engine: executes simulation (evidence: `README.md`)
- Validation and Reports → Traffic Counts: compares counts (evidence: `README.md`)
- Experiment Runner → Freight Modeling: optional analysis
