# axbouf/transport_agent architecture

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

## Overview

Transport is a multi-network public-transport data platform. Its principal runtime workflow schedules realtime feed fetches, converts GTFS-Realtime payloads and writes vehicle positions, trip updates and alerts to PostgreSQL; the web API and experimental agent query transport data, while the React frontend presents the map experience. Static GTFS ingestion and data-warehouse analysis are additional documented capabilities. Source excerpts establish the bus fetch/write path, scheduler dispatch, web query behavior and agent/tool relationship; other documented or indexed subsystems are shown without guessed internal links.

Main entry points: [`web/app.py`](https://github.com/axbouf/transport_agent/blob/main/web/app.py) (Transport API), [`transport_agent/tools.py`](https://github.com/axbouf/transport_agent/blob/main/transport_agent/tools.py) (Query tools), [`realtime/buses/get_vehicle_pos.py`](https://github.com/axbouf/transport_agent/blob/main/realtime/buses/get_vehicle_pos.py) (Bus feed fetchers), [`realtime/pg_writer.py`](https://github.com/axbouf/transport_agent/blob/main/realtime/pg_writer.py) (Postgres writers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_static["Static GTFS"]
  node_static_fetch["Static feed fetch<br/>[get_gtfs_buses.py]"]
  node_static_transit["Static network feeds<br/>[get_gtfs_metro.py]"]
  node_static_trains["Train feed fetch"]
  node_static_load["Static data loader<br/>[load_data.py]"]
end

subgraph group_realtime["Realtime ingestion"]
  node_rt_scheduler["Realtime schedulers<br/>[app.py]"]
  node_rt_fetch["Bus feed fetchers<br/>[get_vehicle_pos.py]"]
  node_rt_bus_jobs["Bus feed jobs<br/>[get_trip_update.py]"]
  node_rt_parser["Feed parsers<br/>[parser.py]"]
  node_rt_schema["Realtime schema<br/>[schema.py]"]
  node_pg_writer["Postgres writers<br/>[pg_writer.py]"]
  node_pg_schema["Postgres schema<br/>[pg_schema.py]"]
end

subgraph group_serving["Query and serving"]
  node_web_api["Transport API<br/>[app.py]"]
  node_web_client["Dashboard client<br/>[app.js]"]
end

subgraph group_client["Frontend"]
  node_frontend_router["Frontend router<br/>[router.tsx]"]
  node_frontend_root["Root route<br/>[__root.tsx]"]
  node_live_map["Live map<br/>[LiveMap.tsx]"]
  node_error_server["SSR error handling<br/>[server.ts]"]
end

subgraph group_agent["Agent tooling"]
  node_agent["Transport agent<br/>[agent.py]"]
  node_tools["Query tools<br/>[tools.py]"]
  node_agent_config["Database config<br/>[config.py]"]
end

subgraph group_warehouse["Warehouse analysis"]
  node_warehouse["Warehouse loaders"]
  node_analysis["Analysis loaders<br/>[load_analysis.py]"]
end

node_user(("Transport user"))
node_gtfs_provider{{"GTFS feeds"}}
node_realtime_provider{{"Transport NSW API"}}
node_postgres[("PostgreSQL")]
node_chat_user(("Chat/API caller"))

node_gtfs_provider -.->|"supplies feeds"| node_static_fetch
node_static_fetch -.->|"loads data"| node_static_load
node_gtfs_provider -.->|"supplies feeds"| node_static_transit
node_gtfs_provider -.->|"supplies feeds"| node_static_trains
node_realtime_provider -->|"serves feed"| node_rt_fetch
node_rt_scheduler -->|"schedules fetch"| node_rt_fetch
node_rt_scheduler -->|"schedules fetch"| node_rt_bus_jobs
node_rt_fetch -->|"writes positions"| node_pg_writer
node_rt_bus_jobs -->|"writes updates"| node_pg_writer
node_rt_parser -->|"uses schema"| node_rt_schema
node_pg_writer -->|"writes realtime"| node_postgres
node_pg_schema -.->|"defines tables"| node_postgres
node_user -.->|"views dashboard"| node_web_client
node_web_client -.->|"requests data"| node_web_api
node_web_api -->|"queries data"| node_postgres
node_chat_user -->|"asks questions"| node_web_api
node_web_api -->|"runs chat query"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"gets DB config"| node_agent_config
node_tools -->|"queries transport"| node_postgres
node_user -.->|"opens app"| node_frontend_router
node_frontend_router -->|"routes to"| node_frontend_root
node_frontend_root -.->|"renders map"| node_live_map
node_error_server -.->|"serves SSR"| node_frontend_root
node_postgres -.->|"supplies data"| node_warehouse
node_warehouse -.->|"builds analysis"| node_analysis

click node_static_fetch "https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_buses.py"
click node_static_transit "https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_metro.py"
click node_static_trains "https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_sydneytrains.py"
click node_static_load "https://github.com/axbouf/transport_agent/blob/main/data/load_data.py"
click node_rt_scheduler "https://github.com/axbouf/transport_agent/blob/main/realtime/buses/app.py"
click node_rt_fetch "https://github.com/axbouf/transport_agent/blob/main/realtime/buses/get_vehicle_pos.py"
click node_rt_bus_jobs "https://github.com/axbouf/transport_agent/blob/main/realtime/buses/get_trip_update.py"
click node_rt_parser "https://github.com/axbouf/transport_agent/blob/main/realtime/parser.py"
click node_rt_schema "https://github.com/axbouf/transport_agent/blob/main/realtime/schema.py"
click node_pg_writer "https://github.com/axbouf/transport_agent/blob/main/realtime/pg_writer.py"
click node_pg_schema "https://github.com/axbouf/transport_agent/blob/main/realtime/pg_schema.py"
click node_web_api "https://github.com/axbouf/transport_agent/blob/main/web/app.py"
click node_web_client "https://github.com/axbouf/transport_agent/blob/main/web/static/app.js"
click node_frontend_router "https://github.com/axbouf/transport_agent/blob/main/frontend/src/router.tsx"
click node_frontend_root "https://github.com/axbouf/transport_agent/blob/main/frontend/src/routes/__root.tsx"
click node_live_map "https://github.com/axbouf/transport_agent/blob/main/frontend/src/components/LiveMap.tsx"
click node_error_server "https://github.com/axbouf/transport_agent/blob/main/frontend/src/server.ts"
click node_agent "https://github.com/axbouf/transport_agent/blob/main/transport_agent/agent.py"
click node_tools "https://github.com/axbouf/transport_agent/blob/main/transport_agent/tools.py"
click node_agent_config "https://github.com/axbouf/transport_agent/blob/main/transport_agent/config.py"
click node_warehouse "https://github.com/axbouf/transport_agent/blob/main/user/datawarehouse/scripts/load_core_transport.py"
click node_analysis "https://github.com/axbouf/transport_agent/blob/main/user/datawarehouse/scripts/load_analysis.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_static_fetch,node_static_transit,node_static_trains,node_static_load,node_user toneBlue
class node_rt_scheduler,node_rt_fetch,node_rt_bus_jobs,node_rt_parser,node_rt_schema,node_pg_writer,node_pg_schema,node_postgres toneAmber
class node_web_api,node_web_client,node_realtime_provider,node_chat_user toneMint
class node_frontend_router,node_frontend_root,node_live_map,node_error_server toneRose
class node_agent,node_tools,node_agent_config,node_gtfs_provider toneIndigo
class node_warehouse,node_analysis toneTeal
```

## Components

### Static GTFS

- [Static feed fetch](https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_buses.py): `data/get_gtfs_buses.py`
- [Static network feeds](https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_metro.py): `data/get_gtfs_metro.py`
- [Train feed fetch](https://github.com/axbouf/transport_agent/blob/main/data/get_gtfs_sydneytrains.py): `data/get_gtfs_sydneytrains.py`
- [Static data loader](https://github.com/axbouf/transport_agent/blob/main/data/load_data.py): `data/load_data.py`

### Realtime ingestion

- [Realtime schedulers](https://github.com/axbouf/transport_agent/blob/main/realtime/buses/app.py): `realtime/buses/app.py`
- [Bus feed fetchers](https://github.com/axbouf/transport_agent/blob/main/realtime/buses/get_vehicle_pos.py): `realtime/buses/get_vehicle_pos.py`
- [Bus feed jobs](https://github.com/axbouf/transport_agent/blob/main/realtime/buses/get_trip_update.py): `realtime/buses/get_trip_update.py`
- [Feed parsers](https://github.com/axbouf/transport_agent/blob/main/realtime/parser.py): `realtime/parser.py`
- [Realtime schema](https://github.com/axbouf/transport_agent/blob/main/realtime/schema.py): `realtime/schema.py`
- [Postgres writers](https://github.com/axbouf/transport_agent/blob/main/realtime/pg_writer.py): `realtime/pg_writer.py`
- [Postgres schema](https://github.com/axbouf/transport_agent/blob/main/realtime/pg_schema.py): `realtime/pg_schema.py`

### Query and serving

- [Transport API](https://github.com/axbouf/transport_agent/blob/main/web/app.py): `web/app.py`
- [Dashboard client](https://github.com/axbouf/transport_agent/blob/main/web/static/app.js): `web/static/app.js`

### Frontend

- [Frontend router](https://github.com/axbouf/transport_agent/blob/main/frontend/src/router.tsx): `frontend/src/router.tsx`
- [Root route](https://github.com/axbouf/transport_agent/blob/main/frontend/src/routes/__root.tsx): `frontend/src/routes/__root.tsx`
- [Live map](https://github.com/axbouf/transport_agent/blob/main/frontend/src/components/LiveMap.tsx): `frontend/src/components/LiveMap.tsx`
- [SSR error handling](https://github.com/axbouf/transport_agent/blob/main/frontend/src/server.ts): `frontend/src/server.ts`

### Agent tooling

- [Transport agent](https://github.com/axbouf/transport_agent/blob/main/transport_agent/agent.py): `transport_agent/agent.py`
- [Query tools](https://github.com/axbouf/transport_agent/blob/main/transport_agent/tools.py): `transport_agent/tools.py`
- [Database config](https://github.com/axbouf/transport_agent/blob/main/transport_agent/config.py): `transport_agent/config.py`

### Warehouse analysis

- [Warehouse loaders](https://github.com/axbouf/transport_agent/blob/main/user/datawarehouse/scripts/load_core_transport.py): `user/datawarehouse/scripts/load_core_transport.py`
- [Analysis loaders](https://github.com/axbouf/transport_agent/blob/main/user/datawarehouse/scripts/load_analysis.py): `user/datawarehouse/scripts/load_analysis.py`

### Other components

- **Transport user**
- **GTFS feeds**
- **Transport NSW API**
- **PostgreSQL**
- **Chat/API caller**

## Connections

- GTFS feeds → Static feed fetch: supplies feeds (evidence: `README.md`)
- Static feed fetch → Static data loader: loads data (evidence: `README.md`)
- GTFS feeds → Static network feeds: supplies feeds (evidence: `README.md`)
- GTFS feeds → Train feed fetch: supplies feeds (evidence: `README.md`)
- Transport NSW API → Bus feed fetchers: serves feed (evidence: `realtime/buses/get_vehicle_pos.py`)
- Realtime schedulers → Bus feed fetchers: schedules fetch (evidence: `realtime/buses/app.py`)
- Realtime schedulers → Bus feed jobs: schedules fetch (evidence: `realtime/buses/app.py`)
- Bus feed fetchers → Postgres writers: writes positions (evidence: `realtime/buses/get_vehicle_pos.py`)
- Bus feed jobs → Postgres writers: writes updates (evidence: `realtime/buses/get_trip_update.py`)
- Feed parsers → Realtime schema: uses schema (evidence: `realtime/parser.py`)
- Postgres writers → PostgreSQL: writes realtime (evidence: `realtime/pg_writer.py`)
- Postgres schema → PostgreSQL: defines tables (evidence: `README.md`)
- Transport user → Dashboard client: views dashboard (evidence: `README.md`)
- Dashboard client → Transport API: requests data (evidence: `README.md`)
- Transport API → PostgreSQL: queries data (evidence: `web/app.py`)
- Chat/API caller → Transport API: asks questions (evidence: `web/app.py`)
- Transport API → Transport agent: runs chat query (evidence: `web/app.py`)
- Transport agent → Query tools: dispatches tools (evidence: `transport_agent/agent.py`)
- Query tools → Database config: gets DB config (evidence: `transport_agent/tools.py`)
- Query tools → PostgreSQL: queries transport (evidence: `transport_agent/tools.py`)
- Transport user → Frontend router: opens app (evidence: `README.md`)
- Frontend router → Root route: routes to (evidence: `frontend/src/routeTree.gen.ts`)
- Root route → Live map: renders map
- SSR error handling → Root route: serves SSR
- PostgreSQL → Warehouse loaders: supplies data (evidence: `README.md`)
- Warehouse loaders → Analysis loaders: builds analysis (evidence: `README.md`)
