# savitp/transit-reliablility architecture

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

## Overview

Transit Reliability turns King County Metro vehicle-position reports into observed stop departures, compares those departures with the static schedule, and presents route/stop reliability and worst-performing views. Riders can also create commute-window delay alerts, which are evaluated in the processing pipeline and delivered through ntfy. The graph reflects the sampled ingestion, processing, API, and notification code; some API endpoints and browser views are documented by excerpts but their full implementations were not sampled.

Main entry points: [`processor.py`](https://github.com/savitp/transit-reliablility/blob/main/processor.py) (Report processor), [`schema.sql`](https://github.com/savitp/transit-reliablility/blob/main/schema.sql) (Transit database), [`api.py`](https://github.com/savitp/transit-reliablility/blob/main/api.py) (Reliability API), [`schedule.py`](https://github.com/savitp/transit-reliablility/blob/main/schedule.py) (Schedule model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Live data collection"]
  node_ingester["Feed ingester<br/>[ingester.py]"]
  node_vehicle_decode["Vehicle decoding<br/>[fetch_vehicles.py]"]
  node_event_stream["Redpanda stream<br/>[stream.py]"]
end

subgraph group_analysis["Schedule and analysis"]
  node_processor["Report processor<br/>[processor.py]"]
  node_schedule_source["Static GTFS schedule"]
  node_schedule["Schedule model<br/>[schedule.py]"]
  node_delay_logic["Departure detection<br/>[delays.py]"]
  node_database[("Transit database<br/>[schema.sql]")]
end

subgraph group_experience["Rider experience"]
  node_api["Reliability API<br/>[api.py]"]
  node_web_app["Transit web app<br/>[app.js]"]
end

subgraph group_alerts["Delay alerts"]
  node_alert_logic["Alert matching<br/>[alerts.py]"]
  node_notifier["Alert notifier<br/>[notifier.py]"]
  node_ntfy{{"ntfy service"}}
end

node_metro_feed(("Metro vehicle feed"))
node_rider(("Rider"))

node_metro_feed -->|"provides feed"| node_ingester
node_ingester -->|"calls"| node_vehicle_decode
node_ingester -->|"publishes reports"| node_event_stream
node_processor -->|"consumes reports"| node_event_stream
node_schedule_source -->|"provides GTFS"| node_schedule
node_processor -->|"loads schedule"| node_schedule
node_processor -->|"processes reports"| node_delay_logic
node_delay_logic -->|"looks up trips"| node_schedule
node_processor -->|"writes departures"| node_database
node_processor -->|"loads subscriptions"| node_database
node_processor -->|"checks departures"| node_alert_logic
node_alert_logic -->|"checks stop times"| node_schedule
node_processor -->|"queues alerts"| node_database
node_rider -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_api
node_api -->|"queries and updates"| node_database
node_database -->|"returns records"| node_api
node_api -->|"returns JSON"| node_web_app
node_notifier -->|"claims and updates alerts"| node_database
node_notifier -->|"sends notifications"| node_ntfy

click node_ingester "https://github.com/savitp/transit-reliablility/blob/main/ingester.py"
click node_vehicle_decode "https://github.com/savitp/transit-reliablility/blob/main/fetch_vehicles.py"
click node_event_stream "https://github.com/savitp/transit-reliablility/blob/main/stream.py"
click node_processor "https://github.com/savitp/transit-reliablility/blob/main/processor.py"
click node_schedule "https://github.com/savitp/transit-reliablility/blob/main/schedule.py"
click node_delay_logic "https://github.com/savitp/transit-reliablility/blob/main/delays.py"
click node_alert_logic "https://github.com/savitp/transit-reliablility/blob/main/alerts.py"
click node_database "https://github.com/savitp/transit-reliablility/blob/main/schema.sql"
click node_api "https://github.com/savitp/transit-reliablility/blob/main/api.py"
click node_web_app "https://github.com/savitp/transit-reliablility/blob/main/static/app.js"
click node_notifier "https://github.com/savitp/transit-reliablility/blob/main/notifier.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_ingester,node_vehicle_decode,node_event_stream toneBlue
class node_processor,node_schedule_source,node_schedule,node_delay_logic,node_database toneAmber
class node_api,node_web_app toneMint
class node_alert_logic,node_notifier,node_ntfy toneRose
class node_metro_feed,node_rider toneIndigo
```

## Components

### Live data collection

- [Feed ingester](https://github.com/savitp/transit-reliablility/blob/main/ingester.py): `ingester.py`
- [Vehicle decoding](https://github.com/savitp/transit-reliablility/blob/main/fetch_vehicles.py): `fetch_vehicles.py`
- [Redpanda stream](https://github.com/savitp/transit-reliablility/blob/main/stream.py): `stream.py`

### Schedule and analysis

- [Report processor](https://github.com/savitp/transit-reliablility/blob/main/processor.py): `processor.py`
- **Static GTFS schedule**
- [Schedule model](https://github.com/savitp/transit-reliablility/blob/main/schedule.py): `schedule.py`
- [Departure detection](https://github.com/savitp/transit-reliablility/blob/main/delays.py): `delays.py`
- [Transit database](https://github.com/savitp/transit-reliablility/blob/main/schema.sql): `schema.sql`

### Rider experience

- [Reliability API](https://github.com/savitp/transit-reliablility/blob/main/api.py): `api.py`
- [Transit web app](https://github.com/savitp/transit-reliablility/blob/main/static/app.js): `static/app.js`

### Delay alerts

- [Alert matching](https://github.com/savitp/transit-reliablility/blob/main/alerts.py): `alerts.py`
- [Alert notifier](https://github.com/savitp/transit-reliablility/blob/main/notifier.py): `notifier.py`
- **ntfy service**

### Other components

- **Metro vehicle feed**
- **Rider**

## Connections

- Metro vehicle feed → Feed ingester: provides feed
- Feed ingester → Vehicle decoding: calls
- Feed ingester → Redpanda stream: publishes reports
- Report processor → Redpanda stream: consumes reports
- Static GTFS schedule → Schedule model: provides GTFS
- Report processor → Schedule model: loads schedule
- Report processor → Departure detection: processes reports
- Departure detection → Schedule model: looks up trips
- Report processor → Transit database: writes departures
- Report processor → Transit database: loads subscriptions
- Report processor → Alert matching: checks departures
- Alert matching → Schedule model: checks stop times
- Report processor → Transit database: queues alerts
- Rider → Transit web app: uses
- Transit web app → Reliability API: requests data
- Reliability API → Transit database: queries and updates
- Transit database → Reliability API: returns records
- Reliability API → Transit web app: returns JSON
- Alert notifier → Transit database: claims and updates alerts
- Alert notifier → ntfy service: sends notifications