# algoarchemist/public-transit architecture

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

- Interactive diagram: https://gitdiagram.com/algoarchemist/public-transit
- Repository: https://github.com/algoarchemist/public-transit

## Overview

#### Purpose and Entry Points
SetuTrack is a real-time public-transport tracking platform for small Punjab cities. It combines passenger/driver mobile workflows, an operations dashboard, live GPS processing, route data ingestion, and ETA/crowding inference. Main runnable entry points are `apps/mobile-app/lib/main.dart`, `apps/admin-dashboard/src/main.tsx`, `services/api-gateway/src/main.ts`, `services/stream-processor/src/consumer.ts`, `services/stream-processor/src/gateway.ts`, and `services/ml-service/app/main.py`.

#### Client Applications
The Flutter app selects Passenger versus Driver/Conductor experiences at startup. Driver flows authenticate, select routes, transmit location, buffer pings, manage trips, and validate tickets; passenger flows expose home, live-map, ticketing, and voice-assistant views. Core paths: `apps/mobile-app/lib/role_selection_screen.dart`, `apps/mobile-app/lib/driver/location_transmitter.dart`, `apps/mobile-app/lib/passenger/live_map_screen.dart`.

The React/Vite admin dashboard is a separate fleet-operations client. It consumes REST and socket abstractions for live fleet state, maps, alerts, route performance, load analytics, model health, and demand/supply planning. Core paths: `apps/admin-dashboard/src/App.tsx`, `apps/admin-dashboard/src/hooks/useFleetSocket.ts`, `apps/admin-dashboard/src/components/FleetMap.tsx`.

#### API and Transaction Boundary
The NestJS API gateway owns client-facing REST domains: authentication, routes/stops, buses, and tickets. It is the fallback/query boundary for clients, distinct from the real-time stream path. Core paths: `services/api-gateway/src/app.module.ts`, `services/api-gateway/src/buses/buses.controller.ts`, `services/api-gateway/src/tickets/tickets.service.ts`.

#### Live Telemetry Processing
The Node/TypeScript stream processor is the central real-time pipeline. It consumes MQTT GPS messages, performs geographic processing, dead reckoning and map matching, persists state, requests ETA scoring, and fan-outs updates through Kafka-compatible streaming and Socket.IO. Its split consumer and gateway processes form an ingestion-to-client boundary. Core paths: `services/stream-processor/src/consumer.ts`, `services/stream-processor/src/mapMatch.ts`, `services/stream-processor/src/gateway.ts`.

#### Data, Routing, and Persistence
Postgres/PostGIS is the durable operational and geospatial store, initialized and evolved through SQL migrations; Redis supports live/cache state. Route snapshots use GTFS-like text plus GeoJSON geometry for Mohali/Tricity. Core paths: `db/migrations/0001_init.sql`, `services/stream-processor/src/pgPersist.ts`, `data/snapshots/mohali-tricity/routes.geojson`.

Geo-ingest builds and reconciles route/stop data from OSM/Overpass, OSRM, and optionally Google Maps before persistence. Core paths: `services/geo-ingest/app/main.py`, `services/geo-ingest/app/reconcile.py`, `services/geo-ingest/app/persist.py`.

#### Prediction and Simulation
The FastAPI ML service provides ETA and crowd inference behind dedicated routers, with baseline behavior until trained artifacts are available. Training code derives features and refreshes statistics from accumulated data. Core paths: `services/ml-service/app/main.py`, `services/ml-service/app/routers/eta.py`, `services/ml-service/train/train_eta.py`.

The simulator provides an end-to-end source when real vehicles are unavailable: it loads snapshots, models congestion/crowding/trips, publishes live telemetry, and can write historical backfill for training. Core paths: `services/simulator/app/main.py`, `services/simulator/app/trip_simulator.py`, `services/simulator/app/live_publisher.py`.

#### Infrastructure and Contracts
Local infrastructure in `docker-compose.yml` supplies Postgres/PostGIS, Redis, Redpanda (Kafka API), and EMQX (MQTT). OSRM container preparation is under `infra/docker/osrm/build.sh`. Type contracts shared by dashboard and stream processor live in `packages/shared-types/src/gps.ts` and `packages/shared-types/src/ml.ts`. The repository is scaffold-stage: these boundaries exist, but live UI, map matching, trained models, and payments remain incomplete.

Main entry points: [`services/stream-processor/src/consumer.ts`](https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/consumer.ts) (Telemetry consumer), [`db/migrations/0001_init.sql`](https://github.com/algoarchemist/public-transit/blob/master/db/migrations/0001_init.sql) (Postgres/PostGIS), [`apps/mobile-app/lib/main.dart`](https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/main.dart) (Flutter mobile app), [`apps/admin-dashboard/src/App.tsx`](https://github.com/algoarchemist/public-transit/blob/master/apps/admin-dashboard/src/App.tsx) (Operations dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_mobile["Flutter mobile app<br/>passenger and driver client<br/>[main.dart]"]
  node_driver_location["Driver location transmitter<br/>mobile telemetry"]
  node_passenger_map["Passenger live map<br/>mobile live view"]
  node_admin["Operations dashboard<br/>React fleet client<br/>[App.tsx]"]
  node_fleet_socket["Fleet socket client<br/>dashboard live adapter<br/>[useFleetSocket.ts]"]
end

subgraph group_realtime["Live telemetry"]
  node_telemetry_consumer["Telemetry consumer<br/>stream ingestion process<br/>[consumer.ts]"]
  node_map_matching["Map matching<br/>geographic processing<br/>[mapMatch.ts]"]
  node_live_gateway{{"Live update gateway<br/>Socket.IO fan-out process<br/>[gateway.ts]"}}
  node_event_bus["Redpanda<br/>Kafka-compatible event stream<br/>[docker-compose.yml]"]
  node_mqtt["EMQX<br/>MQTT broker<br/>[docker-compose.yml]"]
end

subgraph group_data["Data and intelligence"]
  node_postgres[("Postgres/PostGIS<br/>operational geospatial store<br/>[0001_init.sql]")]
  node_redis[("Redis<br/>live state cache<br/>[docker-compose.yml]")]
  node_geo_ingest["Geo ingest<br/>route reconciliation pipeline<br/>[main.py]"]
  node_route_snapshots["Route snapshots<br/>GTFS-like and GeoJSON data<br/>[routes.geojson]"]
  node_ml{{"ML inference service<br/>[main.py]"}}
  node_training["ETA training<br/>model training pipeline<br/>[train_eta.py]"]
  node_simulator["Vehicle simulator<br/>synthetic telemetry source<br/>[main.py]"]
end

node_api{{"API gateway<br/>NestJS REST boundary<br/>[app.module.ts]"}}
node_shared_contracts["Shared contracts<br/>[gps.ts]"]

node_mobile -->|"driver mode"| node_driver_location
node_mobile -->|"passenger mode"| node_passenger_map
node_mobile -->|"REST queries and transactions"| node_api
node_passenger_map -->|"live vehicle updates"| node_live_gateway
node_driver_location -->|"GPS pings"| node_mqtt
node_admin -->|"operations REST"| node_api
node_admin -->|"live fleet state"| node_fleet_socket
node_fleet_socket -->|"socket connection"| node_live_gateway
node_mqtt -->|"telemetry ingestion"| node_telemetry_consumer
node_simulator -->|"synthetic telemetry"| node_mqtt
node_telemetry_consumer -->|"position processing"| node_map_matching
node_map_matching -->|"matched vehicle state"| node_postgres
node_telemetry_consumer -->|"live cache"| node_redis
node_telemetry_consumer -->|"ETA and crowd scoring"| node_ml
node_telemetry_consumer -->|"processed events"| node_event_bus
node_event_bus -->|"fan-out events"| node_live_gateway
node_geo_ingest -->|"reconciles source data"| node_route_snapshots
node_geo_ingest -->|"persists routes and stops"| node_postgres
node_training -->|"historical training data"| node_postgres
node_training -->|"trained artifacts"| node_ml
node_simulator -.->|"historical backfill"| node_postgres
node_shared_contracts -.->|"shared types"| node_admin
node_shared_contracts -.->|"shared types"| node_telemetry_consumer

click node_mobile "https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/main.dart"
click node_driver_location "https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/driver/location_transmitter.dart"
click node_passenger_map "https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/passenger/live_map_screen.dart"
click node_admin "https://github.com/algoarchemist/public-transit/blob/master/apps/admin-dashboard/src/App.tsx"
click node_fleet_socket "https://github.com/algoarchemist/public-transit/blob/master/apps/admin-dashboard/src/hooks/useFleetSocket.ts"
click node_api "https://github.com/algoarchemist/public-transit/blob/master/services/api-gateway/src/app.module.ts"
click node_telemetry_consumer "https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/consumer.ts"
click node_map_matching "https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/mapMatch.ts"
click node_live_gateway "https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/gateway.ts"
click node_event_bus "https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml"
click node_mqtt "https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml"
click node_postgres "https://github.com/algoarchemist/public-transit/blob/master/db/migrations/0001_init.sql"
click node_redis "https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml"
click node_geo_ingest "https://github.com/algoarchemist/public-transit/blob/master/services/geo-ingest/app/main.py"
click node_route_snapshots "https://github.com/algoarchemist/public-transit/blob/master/data/snapshots/mohali-tricity/routes.geojson"
click node_ml "https://github.com/algoarchemist/public-transit/blob/master/services/ml-service/app/main.py"
click node_training "https://github.com/algoarchemist/public-transit/blob/master/services/ml-service/train/train_eta.py"
click node_simulator "https://github.com/algoarchemist/public-transit/blob/master/services/simulator/app/main.py"
click node_shared_contracts "https://github.com/algoarchemist/public-transit/blob/master/packages/shared-types/src/gps.ts"

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_mobile,node_driver_location,node_passenger_map,node_admin,node_fleet_socket toneBlue
class node_telemetry_consumer,node_map_matching,node_live_gateway,node_event_bus,node_mqtt toneAmber
class node_postgres,node_redis,node_geo_ingest,node_route_snapshots,node_ml,node_training,node_simulator toneMint
class node_api,node_shared_contracts toneNeutral
```

## Components

### Client apps

- [Flutter mobile app](https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/main.dart): passenger and driver client · Selects passenger or driver/conductor workflows. · `apps/mobile-app/lib/main.dart`
- [Driver location transmitter](https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/driver/location_transmitter.dart): mobile telemetry · Buffers and transmits vehicle pings. · `apps/mobile-app/lib/driver/location_transmitter.dart`
- [Passenger live map](https://github.com/algoarchemist/public-transit/blob/master/apps/mobile-app/lib/passenger/live_map_screen.dart): mobile live view · `apps/mobile-app/lib/passenger/live_map_screen.dart`
- [Operations dashboard](https://github.com/algoarchemist/public-transit/blob/master/apps/admin-dashboard/src/App.tsx): React fleet client · `apps/admin-dashboard/src/App.tsx`
- [Fleet socket client](https://github.com/algoarchemist/public-transit/blob/master/apps/admin-dashboard/src/hooks/useFleetSocket.ts): dashboard live adapter · `apps/admin-dashboard/src/hooks/useFleetSocket.ts`

### Live telemetry

- [Telemetry consumer](https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/consumer.ts): stream ingestion process · Processes MQTT GPS, geographic state, and ETA requests. · `services/stream-processor/src/consumer.ts`
- [Map matching](https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/mapMatch.ts): geographic processing · Applies dead reckoning and route matching. · `services/stream-processor/src/mapMatch.ts`
- [Live update gateway](https://github.com/algoarchemist/public-transit/blob/master/services/stream-processor/src/gateway.ts): Socket.IO fan-out process · `services/stream-processor/src/gateway.ts`
- [Redpanda](https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml): Kafka-compatible event stream · `docker-compose.yml`
- [EMQX](https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml): MQTT broker · `docker-compose.yml`

### Data and intelligence

- [Postgres/PostGIS](https://github.com/algoarchemist/public-transit/blob/master/db/migrations/0001_init.sql): operational geospatial store · `db/migrations/0001_init.sql`
- [Redis](https://github.com/algoarchemist/public-transit/blob/master/docker-compose.yml): live state cache · `docker-compose.yml`
- [Geo ingest](https://github.com/algoarchemist/public-transit/blob/master/services/geo-ingest/app/main.py): route reconciliation pipeline · Builds route and stop data from external map sources. · `services/geo-ingest/app/main.py`
- [Route snapshots](https://github.com/algoarchemist/public-transit/blob/master/data/snapshots/mohali-tricity/routes.geojson): GTFS-like and GeoJSON data · `data/snapshots/mohali-tricity/routes.geojson`
- [ML inference service](https://github.com/algoarchemist/public-transit/blob/master/services/ml-service/app/main.py): FastAPI ETA and crowd scoring · Uses baseline behavior until trained artifacts exist. · `services/ml-service/app/main.py`
- [ETA training](https://github.com/algoarchemist/public-transit/blob/master/services/ml-service/train/train_eta.py): model training pipeline · Derives features and refreshes accumulated statistics. · `services/ml-service/train/train_eta.py`
- [Vehicle simulator](https://github.com/algoarchemist/public-transit/blob/master/services/simulator/app/main.py): synthetic telemetry source · Publishes live trips and can backfill training history. · `services/simulator/app/main.py`

### Other components

- [API gateway](https://github.com/algoarchemist/public-transit/blob/master/services/api-gateway/src/app.module.ts): NestJS REST boundary · Owns authentication, routes, buses, and tickets. · `services/api-gateway/src/app.module.ts`
- [Shared contracts](https://github.com/algoarchemist/public-transit/blob/master/packages/shared-types/src/gps.ts): TypeScript telemetry and ML types · `packages/shared-types/src/gps.ts`

## Connections

- Flutter mobile app → Driver location transmitter: driver mode
- Flutter mobile app → Passenger live map: passenger mode
- Flutter mobile app → API gateway: REST queries and transactions
- Passenger live map → Live update gateway: live vehicle updates
- Driver location transmitter → EMQX: GPS pings
- Operations dashboard → API gateway: operations REST
- Operations dashboard → Fleet socket client: live fleet state
- Fleet socket client → Live update gateway: socket connection
- EMQX → Telemetry consumer: telemetry ingestion
- Vehicle simulator → EMQX: synthetic telemetry
- Telemetry consumer → Map matching: position processing
- Map matching → Postgres/PostGIS: matched vehicle state
- Telemetry consumer → Redis: live cache
- Telemetry consumer → ML inference service: ETA and crowd scoring
- Telemetry consumer → Redpanda: processed events
- Redpanda → Live update gateway: fan-out events
- Geo ingest → Route snapshots: reconciles source data
- Geo ingest → Postgres/PostGIS: persists routes and stops
- ETA training → Postgres/PostGIS: historical training data
- ETA training → ML inference service: trained artifacts
- Vehicle simulator → Postgres/PostGIS: historical backfill
- Shared contracts → Operations dashboard: shared types
- Shared contracts → Telemetry consumer: shared types