# hytangs/vigo-py architecture

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

- Interactive diagram: https://gitdiagram.com/hytangs/vigo-py
- Repository: https://github.com/hytangs/vigo-py

## Overview

VIGO Python is a wrapper for building and querying transport City models through a compatible VIGO Engine runtime. The principal workflow is GTFS and OSM inputs → City build/open → Route, Matrix, or Reach queries → Results that can be interpreted, exported, or compared. Scenarios provide optional planned-service inputs for Reach; supplied traffic supports Drive Route/Matrix. The sampled code shows runtime selection and resident Route execution; other query paths and result behavior are represented only where documented. Core behavior is concentrated in `vigo/model.py` and `vigo/runtime.py`.

Main entry points: [`vigo/__init__.py`](https://github.com/hytangs/vigo-py/blob/main/vigo/__init__.py) (VIGO API), [`vigo/model.py`](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py) (Build City), [`vigo/runtime.py`](https://github.com/hytangs/vigo-py/blob/main/vigo/runtime.py) (Runtime selection), [`vigo/progress.py`](https://github.com/hytangs/vigo-py/blob/main/vigo/progress.py) (Build progress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_city["City lifecycle"]
  node_api["VIGO API<br/>[__init__.py]"]
  node_build["Build City<br/>[model.py]"]
  node_city_model["City model<br/>[model.py]"]
  node_city_files["City directory"]
end

subgraph group_query["Queries and results"]
  node_scenario["Scenario<br/>[model.py]"]
  node_route["Route query<br/>[model.py]"]
  node_matrix["Matrix query<br/>[model.py]"]
  node_reach["Reach query<br/>[model.py]"]
  node_result["Result<br/>[model.py]"]
  node_compare["Compare results<br/>[model.py]"]
end

subgraph group_execution["Runtime execution"]
  node_runtime_select["Runtime selection<br/>[runtime.py]"]
  node_engine["VIGO Engine"]
  node_route_stream["Route stream<br/>[model.py]"]
  node_progress["Build progress<br/>[progress.py]"]
end

node_python_user(("Python caller"))
node_gtfs["GTFS data"]
node_osm["OSM data"]

node_python_user -->|"calls"| node_api
node_api -->|"exposes"| node_build
node_api -->|"exposes"| node_city_model
node_api -->|"exposes"| node_route
node_api -->|"exposes"| node_matrix
node_api -->|"exposes"| node_reach
node_api -->|"exposes"| node_scenario
node_api -->|"exposes"| node_compare
node_build -->|"reads"| node_gtfs
node_build -->|"reads"| node_osm
node_build -->|"resolves runtime"| node_runtime_select
node_build -->|"invokes build"| node_engine
node_build -->|"creates"| node_city_files
node_build -->|"opens"| node_city_model
node_city_model -->|"opens"| node_city_files
node_city_model -->|"resolves runtime"| node_runtime_select
node_runtime_select -->|"checks capabilities"| node_engine
node_city_model -->|"uses resident route"| node_route_stream
node_route_stream -->|"sends requests"| node_engine
node_city_model -->|"runs queries"| node_engine
node_city_model -->|"returns query result"| node_result
node_scenario -.->|"supports planned service"| node_reach
node_route -->|"produces"| node_result
node_matrix -->|"produces"| node_result
node_reach -->|"produces"| node_result
node_compare -->|"compares"| node_result
node_result -->|"returns"| node_python_user
node_build -.->|"reports progress"| node_progress

click node_api "https://github.com/hytangs/vigo-py/blob/main/vigo/__init__.py"
click node_build "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_city_model "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_scenario "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_route "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_matrix "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_reach "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_result "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_compare "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_runtime_select "https://github.com/hytangs/vigo-py/blob/main/vigo/runtime.py"
click node_route_stream "https://github.com/hytangs/vigo-py/blob/main/vigo/model.py"
click node_progress "https://github.com/hytangs/vigo-py/blob/main/vigo/progress.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_api,node_build,node_city_model,node_city_files toneBlue
class node_scenario,node_route,node_matrix,node_reach,node_result,node_compare toneAmber
class node_runtime_select,node_engine,node_route_stream,node_progress toneMint
class node_python_user,node_gtfs,node_osm toneIndigo
```

## Components

### City lifecycle

- [VIGO API](https://github.com/hytangs/vigo-py/blob/main/vigo/__init__.py): `vigo/__init__.py`
- [Build City](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [City model](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- **City directory**

### Queries and results

- [Scenario](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Route query](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Matrix query](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Reach query](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Result](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Compare results](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`

### Runtime execution

- [Runtime selection](https://github.com/hytangs/vigo-py/blob/main/vigo/runtime.py): `vigo/runtime.py`
- **VIGO Engine**
- [Route stream](https://github.com/hytangs/vigo-py/blob/main/vigo/model.py): `vigo/model.py`
- [Build progress](https://github.com/hytangs/vigo-py/blob/main/vigo/progress.py): `vigo/progress.py`

### Other components

- **Python caller**
- **GTFS data**
- **OSM data**

## Connections

- Python caller → VIGO API: calls
- VIGO API → Build City: exposes
- VIGO API → City model: exposes
- VIGO API → Route query: exposes
- VIGO API → Matrix query: exposes
- VIGO API → Reach query: exposes
- VIGO API → Scenario: exposes
- VIGO API → Compare results: exposes
- Build City → GTFS data: reads
- Build City → OSM data: reads
- Build City → Runtime selection: resolves runtime
- Build City → VIGO Engine: invokes build
- Build City → City directory: creates
- Build City → City model: opens
- City model → City directory: opens
- City model → Runtime selection: resolves runtime
- Runtime selection → VIGO Engine: checks capabilities
- City model → Route stream: uses resident route
- Route stream → VIGO Engine: sends requests
- City model → VIGO Engine: runs queries
- City model → Result: returns query result
- Scenario → Reach query: supports planned service
- Route query → Result: produces
- Matrix query → Result: produces
- Reach query → Result: produces
- Compare results → Result: compares
- Result → Python caller: returns
- Build City → Build progress: reports progress