# gnoccoalpesto/segui_bus architecture

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

- Interactive diagram: https://gitdiagram.com/gnoccoalpesto/segui_bus
- Repository: https://github.com/gnoccoalpesto/segui_bus

## Overview

segui_bus monitors SETA buses and alerts when a selected vehicle or line’s bus approaches a chosen stop. The long-running watch path loads presets and static GTFS, obtains real-time snapshots, builds schedule-aware reports, evaluates proximity and alarm state, then dispatches notifications; the CLI also supports one-shot line, stop, and vehicle lookups. The graph preserves preset-command and Home Assistant capabilities documented in the README. Edges are limited to relationships supported by excerpts, the source index, or README; unsampled details are not assumed.

Main entry points: [`src/segui_bus/__main__.py`](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/__main__.py) (CLI runtime), [`src/segui_bus/report.py`](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/report.py) (Schedule-aware report), [`src/segui_bus/service/watch.py`](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/service/watch.py) (Watch and alarm state), [`src/segui_bus/static_gtfs.py`](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/static_gtfs.py) (Static GTFS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_cli["CLI runtime<br/>[__main__.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_watch["Watch and alarm state<br/>[watch.py]"]
end

subgraph group_feeds["Transit feeds"]
  node_transport["Realtime transport<br/>[transport.py]"]
  node_live["Live snapshots<br/>[live.py]"]
  node_fetch["Realtime fetch<br/>[fetch.py]"]
  node_rtparse["GTFS-RT parser<br/>[gtfsrt.py]"]
  node_static[("Static GTFS<br/>[static_gtfs.py]")]
end

subgraph group_analysis["Transit analysis"]
  node_domain["Transit domain<br/>[domain.py]"]
  node_lookup["Line and stop lookup<br/>[lookup.py]"]
  node_geo["Geospatial helpers<br/>[geo.py]"]
  node_progress["Trip progress<br/>[progress.py]"]
  node_clock["Service-day clock<br/>[clock.py]"]
  node_report["Schedule-aware report<br/>[report.py]"]
  node_proximity["Proximity evaluation<br/>[proximity.py]"]
end

subgraph group_alerts["Presets and alerts"]
  node_preset[("Preset store<br/>[presets.py]")]
  node_commands["Telegram commands<br/>[commands.py]"]
  node_notifier["Telegram notifier<br/>[telegram.py]"]
end

node_rider(("Rider / operator"))
node_busone{{"BusOne feed service"}}
node_telegram{{"Telegram service"}}
node_ha(("Home Assistant"))

node_rider -->|"invokes"| node_cli
node_cli -->|"loads"| node_settings
node_cli -->|"starts"| node_transport
node_cli -->|"fetches"| node_live
node_cli -->|"loads"| node_preset
node_cli -->|"configures"| node_watch
node_cli -->|"runs"| node_commands
node_cli -->|"dispatches"| node_notifier
node_transport -->|"retrieves feeds"| node_busone
node_transport -->|"uses"| node_settings
node_live -->|"fetches"| node_fetch
node_live -->|"uses"| node_static
node_fetch -->|"uses"| node_settings
node_fetch -->|"parses"| node_rtparse
node_static -->|"downloads GTFS"| node_busone
node_static -->|"uses"| node_settings
node_rtparse -->|"produces objects"| node_domain
node_lookup -->|"resolves routes"| node_static
node_lookup -->|"measures distance"| node_geo
node_lookup -->|"uses objects"| node_domain
node_progress -->|"uses geometry"| node_geo
node_progress -->|"uses objects"| node_domain
node_report -->|"enriches trips"| node_lookup
node_report -->|"computes progress"| node_progress
node_report -->|"uses proximity"| node_proximity
node_report -->|"reads schedule"| node_static
node_report -->|"converts times"| node_clock
node_watch -->|"reads snapshots"| node_live
node_watch -->|"builds report"| node_report
node_watch -->|"evaluates alarms"| node_proximity
node_preset -->|"resolves against"| node_static
node_commands -->|"manages"| node_preset
node_commands -->|"updates watches"| node_watch
node_commands -->|"uses"| node_notifier
node_notifier -->|"sends alerts"| node_telegram
node_watch -.->|"provides data"| node_ha

click node_cli "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/__main__.py"
click node_settings "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/config.py"
click node_transport "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/service/transport.py"
click node_live "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/live.py"
click node_fetch "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/fetch.py"
click node_rtparse "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/gtfsrt.py"
click node_static "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/static_gtfs.py"
click node_domain "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/domain.py"
click node_lookup "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/lookup.py"
click node_geo "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/geo.py"
click node_progress "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/progress.py"
click node_clock "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/clock.py"
click node_report "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/report.py"
click node_proximity "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/proximity.py"
click node_watch "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/service/watch.py"
click node_preset "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/presets.py"
click node_commands "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/notify/commands.py"
click node_notifier "https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/notify/telegram.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_cli,node_settings,node_watch toneBlue
class node_transport,node_live,node_fetch,node_rtparse,node_static toneAmber
class node_domain,node_lookup,node_geo,node_progress,node_clock,node_report,node_proximity toneMint
class node_preset,node_commands,node_notifier toneRose
class node_rider,node_busone,node_telegram,node_ha toneIndigo
```

## Components

### Runtime orchestration

- [CLI runtime](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/__main__.py): `src/segui_bus/__main__.py`
- [Runtime settings](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/config.py): `src/segui_bus/config.py`
- [Watch and alarm state](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/service/watch.py): `src/segui_bus/service/watch.py`

### Transit feeds

- [Realtime transport](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/service/transport.py): `src/segui_bus/service/transport.py`
- [Live snapshots](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/live.py): `src/segui_bus/live.py`
- [Realtime fetch](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/fetch.py): `src/segui_bus/fetch.py`
- [GTFS-RT parser](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/gtfsrt.py): `src/segui_bus/gtfsrt.py`
- [Static GTFS](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/static_gtfs.py): `src/segui_bus/static_gtfs.py`

### Transit analysis

- [Transit domain](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/domain.py): `src/segui_bus/domain.py`
- [Line and stop lookup](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/lookup.py): `src/segui_bus/lookup.py`
- [Geospatial helpers](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/geo.py): `src/segui_bus/geo.py`
- [Trip progress](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/progress.py): `src/segui_bus/progress.py`
- [Service-day clock](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/clock.py): `src/segui_bus/clock.py`
- [Schedule-aware report](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/report.py): `src/segui_bus/report.py`
- [Proximity evaluation](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/proximity.py): `src/segui_bus/proximity.py`

### Presets and alerts

- [Preset store](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/presets.py): `src/segui_bus/presets.py`
- [Telegram commands](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/notify/commands.py): `src/segui_bus/notify/commands.py`
- [Telegram notifier](https://github.com/gnoccoalpesto/segui_bus/blob/main/src/segui_bus/notify/telegram.py): `src/segui_bus/notify/telegram.py`

### Other components

- **Rider / operator**
- **BusOne feed service**
- **Telegram service**
- **Home Assistant**

## Connections

- Rider / operator → CLI runtime: invokes (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Runtime settings: loads (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Realtime transport: starts (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Live snapshots: fetches (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Preset store: loads (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Watch and alarm state: configures (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Telegram commands: runs (evidence: `src/segui_bus/__main__.py`)
- CLI runtime → Telegram notifier: dispatches (evidence: `src/segui_bus/__main__.py`)
- Realtime transport → BusOne feed service: retrieves feeds (evidence: `README.md`)
- Realtime transport → Runtime settings: uses (evidence: `src/segui_bus/service/transport.py`)
- Live snapshots → Realtime fetch: fetches (evidence: `src/segui_bus/live.py`)
- Live snapshots → Static GTFS: uses (evidence: `src/segui_bus/live.py`)
- Realtime fetch → Runtime settings: uses (evidence: `src/segui_bus/fetch.py`)
- Realtime fetch → GTFS-RT parser: parses (evidence: `src/segui_bus/fetch.py`)
- Static GTFS → BusOne feed service: downloads GTFS (evidence: `src/segui_bus/static_gtfs.py`)
- Static GTFS → Runtime settings: uses (evidence: `src/segui_bus/static_gtfs.py`)
- GTFS-RT parser → Transit domain: produces objects (evidence: `src/segui_bus/gtfsrt.py`)
- Line and stop lookup → Static GTFS: resolves routes (evidence: `src/segui_bus/lookup.py`)
- Line and stop lookup → Geospatial helpers: measures distance (evidence: `src/segui_bus/lookup.py`)
- Line and stop lookup → Transit domain: uses objects (evidence: `src/segui_bus/lookup.py`)
- Trip progress → Geospatial helpers: uses geometry (evidence: `src/segui_bus/progress.py`)
- Trip progress → Transit domain: uses objects (evidence: `src/segui_bus/progress.py`)
- Schedule-aware report → Line and stop lookup: enriches trips (evidence: `src/segui_bus/report.py`)
- Schedule-aware report → Trip progress: computes progress (evidence: `src/segui_bus/report.py`)
- Schedule-aware report → Proximity evaluation: uses proximity (evidence: `src/segui_bus/report.py`)
- Schedule-aware report → Static GTFS: reads schedule (evidence: `src/segui_bus/report.py`)
- Schedule-aware report → Service-day clock: converts times (evidence: `src/segui_bus/report.py`)
- Watch and alarm state → Live snapshots: reads snapshots (evidence: `src/segui_bus/service/watch.py`)
- Watch and alarm state → Schedule-aware report: builds report (evidence: `src/segui_bus/service/watch.py`)
- Watch and alarm state → Proximity evaluation: evaluates alarms (evidence: `src/segui_bus/service/watch.py`)
- Preset store → Static GTFS: resolves against (evidence: `src/segui_bus/presets.py`)
- Telegram commands → Preset store: manages (evidence: `src/segui_bus/notify/commands.py`)
- Telegram commands → Watch and alarm state: updates watches (evidence: `src/segui_bus/notify/commands.py`)
- Telegram commands → Telegram notifier: uses (evidence: `src/segui_bus/notify/commands.py`)
- Telegram notifier → Telegram service: sends alerts (evidence: `src/segui_bus/notify/telegram.py`)
- Watch and alarm state → Home Assistant: provides data (evidence: `README.md`)
