# hytangs/vigo architecture

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

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

## Overview

VIGO builds a portable City from GTFS and OpenStreetMap, then answers Route, Matrix, and Reach queries through its Rust engine. The compiler, standalone engine, Studio, and Python package are distinct interfaces to this workflow. Studio also supports visual network and live-service inspection and scenario exploration; agency analysis provides service and network assessments. The graph preserves these documented capabilities, but sampled source is incomplete, so some documented links use README evidence rather than inspected call sites.

Main entry points: [`native/vigo-routing-kernel/src/standalone/query.rs`](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/standalone/query.rs) (Standalone query API), [`src/App.tsx`](https://github.com/hytangs/vigo/blob/main/src/App.tsx) (Studio application), [`src/agency/serviceInspection.mjs`](https://github.com/hytangs/vigo/blob/main/src/agency/serviceInspection.mjs) (Service inspection), [`src/cli/vigo.ts`](https://github.com/hytangs/vigo/blob/main/src/cli/vigo.ts) (City compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_city["City preparation"]
  node_compiler["City compiler<br/>[vigo.ts]"]
  node_city_store[("Portable City")]
  node_street_store[("Street data")]
end

subgraph group_engine["Routing engine"]
  node_kernel_api["Standalone query API<br/>[query.rs]"]
  node_routing["Journey routing<br/>[exact_routing.rs]"]
  node_matrix["Travel-time matrix<br/>[endpoint_batch.rs]"]
  node_reach["Reach analysis<br/>[reach.ts]"]
  node_results["Result formatting<br/>[presentation.rs]"]
end

subgraph group_studio["VIGO Studio"]
  node_studio_app["Studio application<br/>[App.tsx]"]
  node_routing_controls["Routing controls"]
  node_api["Application API<br/>[api.ts]"]
  node_map_surface["Map and results<br/>[RouteSurface.tsx]"]
  node_scenario["Scenario planning<br/>[reach.ts]"]
end

subgraph group_agency["Agency intelligence"]
  node_service_inspection["Service inspection"]
  node_network_assessment["Network assessment"]
  node_live_data["Live service data"]
end

subgraph group_interfaces["Other interfaces"]
  node_python["Python interface<br/>[runtime.py]"]
  node_engine_cli["Engine CLI and HTTP<br/>[vigo.rs]"]
end

node_gtfs_osm(("GTFS and OSM"))
node_studio_user(("Studio user"))
node_agency_user(("Agency analyst"))

node_gtfs_osm -->|"builds from"| node_compiler
node_compiler -.->|"prepares City"| node_city_store
node_compiler -.->|"prepares streets"| node_street_store
node_city_store -.->|"queries"| node_kernel_api
node_street_store -.->|"queries"| node_kernel_api
node_studio_user -->|"uses"| node_studio_app
node_studio_app -.->|"starts routing"| node_routing_controls
node_routing_controls -->|"requests routes"| node_api
node_api -.->|"sends queries"| node_kernel_api
node_kernel_api -.->|"routes journeys"| node_routing
node_kernel_api -->|"computes matrices"| node_matrix
node_kernel_api -->|"computes reach"| node_reach
node_kernel_api -->|"formats results"| node_results
node_api -.->|"supplies map data"| node_map_surface
node_studio_app -.->|"plans scenarios"| node_scenario
node_agency_user -.->|"investigates service"| node_service_inspection
node_service_inspection -->|"uses feed state"| node_live_data
node_service_inspection -->|"diagnoses network"| node_network_assessment
node_studio_app -->|"inspects live service"| node_service_inspection
node_python -->|"runs queries"| node_kernel_api
node_engine_cli -->|"runs queries"| node_kernel_api

click node_compiler "https://github.com/hytangs/vigo/blob/main/src/cli/vigo.ts"
click node_city_store "https://github.com/hytangs/vigo/blob/main/src/server/national-gtfs-store.mjs"
click node_street_store "https://github.com/hytangs/vigo/blob/main/src/server/national-osm-store.mjs"
click node_studio_app "https://github.com/hytangs/vigo/blob/main/src/App.tsx"
click node_routing_controls "https://github.com/hytangs/vigo/blob/main/src/app/useNationalRouting.ts"
click node_api "https://github.com/hytangs/vigo/blob/main/src/app/api.ts"
click node_map_surface "https://github.com/hytangs/vigo/blob/main/src/components/studio/RouteSurface.tsx"
click node_scenario "https://github.com/hytangs/vigo/blob/main/src/reach.ts"
click node_kernel_api "https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/standalone/query.rs"
click node_routing "https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/exact_routing.rs"
click node_matrix "https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/endpoint_batch.rs"
click node_reach "https://github.com/hytangs/vigo/blob/main/src/reach.ts"
click node_results "https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/presentation.rs"
click node_service_inspection "https://github.com/hytangs/vigo/blob/main/src/agency/serviceInspection.mjs"
click node_network_assessment "https://github.com/hytangs/vigo/blob/main/src/agency/serviceAssessment.mjs"
click node_live_data "https://github.com/hytangs/vigo/blob/main/src/agency/realtimeIntelligence.mjs"
click node_python "https://github.com/hytangs/vigo/blob/main/python/vigo/runtime.py"
click node_engine_cli "https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/bin/vigo.rs"

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_compiler,node_city_store,node_street_store,node_studio_user toneBlue
class node_kernel_api,node_routing,node_matrix,node_reach,node_results toneAmber
class node_studio_app,node_routing_controls,node_api,node_map_surface,node_scenario toneMint
class node_service_inspection,node_network_assessment,node_live_data toneRose
class node_python,node_engine_cli,node_gtfs_osm,node_agency_user toneIndigo
```

## Components

### City preparation

- [City compiler](https://github.com/hytangs/vigo/blob/main/src/cli/vigo.ts): `src/cli/vigo.ts`
- [Portable City](https://github.com/hytangs/vigo/blob/main/src/server/national-gtfs-store.mjs): `src/server/national-gtfs-store.mjs`
- [Street data](https://github.com/hytangs/vigo/blob/main/src/server/national-osm-store.mjs): `src/server/national-osm-store.mjs`

### Routing engine

- [Standalone query API](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/standalone/query.rs): `native/vigo-routing-kernel/src/standalone/query.rs`
- [Journey routing](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/exact_routing.rs): `native/vigo-routing-kernel/src/exact_routing.rs`
- [Travel-time matrix](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/endpoint_batch.rs): `native/vigo-routing-kernel/src/endpoint_batch.rs`
- [Reach analysis](https://github.com/hytangs/vigo/blob/main/src/reach.ts): `src/reach.ts`
- [Result formatting](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/presentation.rs): `native/vigo-routing-kernel/src/presentation.rs`

### VIGO Studio

- [Studio application](https://github.com/hytangs/vigo/blob/main/src/App.tsx): `src/App.tsx`
- [Routing controls](https://github.com/hytangs/vigo/blob/main/src/app/useNationalRouting.ts): `src/app/useNationalRouting.ts`
- [Application API](https://github.com/hytangs/vigo/blob/main/src/app/api.ts): `src/app/api.ts`
- [Map and results](https://github.com/hytangs/vigo/blob/main/src/components/studio/RouteSurface.tsx): `src/components/studio/RouteSurface.tsx`
- [Scenario planning](https://github.com/hytangs/vigo/blob/main/src/reach.ts): `src/reach.ts`

### Agency intelligence

- [Service inspection](https://github.com/hytangs/vigo/blob/main/src/agency/serviceInspection.mjs): `src/agency/serviceInspection.mjs`
- [Network assessment](https://github.com/hytangs/vigo/blob/main/src/agency/serviceAssessment.mjs): `src/agency/serviceAssessment.mjs`
- [Live service data](https://github.com/hytangs/vigo/blob/main/src/agency/realtimeIntelligence.mjs): `src/agency/realtimeIntelligence.mjs`

### Other interfaces

- [Python interface](https://github.com/hytangs/vigo/blob/main/python/vigo/runtime.py): `python/vigo/runtime.py`
- [Engine CLI and HTTP](https://github.com/hytangs/vigo/blob/main/native/vigo-routing-kernel/src/bin/vigo.rs): `native/vigo-routing-kernel/src/bin/vigo.rs`

### Other components

- **GTFS and OSM**
- **Studio user**
- **Agency analyst**

## Connections

- GTFS and OSM → City compiler: builds from (evidence: `README.md`)
- City compiler → Portable City: prepares City
- City compiler → Street data: prepares streets
- Portable City → Standalone query API: queries
- Street data → Standalone query API: queries
- Studio user → Studio application: uses (evidence: `README.md`)
- Studio application → Routing controls: starts routing (evidence: `src/App.tsx`)
- Routing controls → Application API: requests routes (evidence: `src/app/useNationalRouting.ts`)
- Application API → Standalone query API: sends queries
- Standalone query API → Journey routing: routes journeys
- Standalone query API → Travel-time matrix: computes matrices (evidence: `README.md`)
- Standalone query API → Reach analysis: computes reach (evidence: `README.md`)
- Standalone query API → Result formatting: formats results (evidence: `native/vigo-routing-kernel/src/standalone/query.rs`)
- Application API → Map and results: supplies map data (evidence: `src/components/studio/RouteSurface.tsx`)
- Studio application → Scenario planning: plans scenarios
- Agency analyst → Service inspection: investigates service
- Service inspection → Live service data: uses feed state (evidence: `src/agency/serviceInspection.mjs`)
- Service inspection → Network assessment: diagnoses network (evidence: `src/agency/serviceInspection.mjs`)
- Studio application → Service inspection: inspects live service (evidence: `README.md`)
- Python interface → Standalone query API: runs queries (evidence: `README.md`)
- Engine CLI and HTTP → Standalone query API: runs queries (evidence: `README.md`)