# kx1t/docker-commuterrail architecture

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

## Overview

docker-commuterrail combines a browser departures dashboard with a Dockerized, in-memory transit cache for Paris PRIM and Boston MBTA. The main flow is browser selection and refresh → local service request → cache hit or upstream refresh → departures displayed; vehicle-map snapshots and cache diagnostics are additional capabilities. The server excerpt is partial, so the graph keeps server responsibilities at a coarse level and uses README statements for documented UI and diagnostics behavior rather than implying unshown handler internals.

Main entry points: [`app/server.py`](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py) (HTTP cache service), [`index.html`](https://github.com/kx1t/docker-commuterrail/blob/main/index.html) (Departures dashboard), [`app/map_snapshot.py`](https://github.com/kx1t/docker-commuterrail/blob/main/app/map_snapshot.py) (Vehicle snapshot extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser dashboard"]
  node_dashboard["Departures dashboard<br/>[index.html]"]
  node_settings["Transit settings<br/>[index.html]"]
  node_departures["Departure selection<br/>[index.html]"]
  node_map_dialog["Snapshot map dialog<br/>[index.html]"]
end

subgraph group_service["Cache service"]
  node_cache_server["HTTP cache service<br/>[server.py]"]
  node_transit_modes["Transit mode handling<br/>[server.py]"]
  node_cache_lifecycle["Cache and refresh<br/>[server.py]"]
  node_upstream_fetch["Upstream data fetch<br/>[server.py]"]
  node_snapshot_builder["Vehicle snapshot extraction<br/>[map_snapshot.py]"]
end

subgraph group_transit["Transit data"]
  node_prim["Paris PRIM"]
  node_mbta["Boston MBTA"]
end

subgraph group_diagnostics["Cache diagnostics"]
  node_diagnostics_view["Diagnostics view<br/>[index.html]"]
  node_stats_api["Stats endpoint<br/>[server.py]"]
  node_stats_journal[("Stats journal<br/>[server.py]")]
  node_client_provenance["Client provenance<br/>[server.py]"]
end

node_rider(("Rider"))

node_rider -->|"views"| node_dashboard
node_dashboard -->|"opens"| node_settings
node_settings -->|"selects mode"| node_departures
node_dashboard -->|"requests departures"| node_cache_server
node_departures -->|"sends transit"| node_transit_modes
node_cache_server -.->|"routes request"| node_transit_modes
node_cache_server -->|"gets or refreshes"| node_cache_lifecycle
node_cache_lifecycle -->|"refreshes stale data"| node_upstream_fetch
node_upstream_fetch -->|"fetches Paris data"| node_prim
node_upstream_fetch -->|"fetches Boston data"| node_mbta
node_cache_server -->|"builds snapshots"| node_snapshot_builder
node_departures -->|"opens map"| node_map_dialog
node_map_dialog -->|"requests position"| node_cache_server
node_rider -->|"opens diagnostics"| node_diagnostics_view
node_diagnostics_view -->|"reads statistics"| node_stats_api
node_stats_api -.->|"reads and records"| node_stats_journal
node_stats_api -->|"reports clients"| node_client_provenance
node_cache_server -->|"serves endpoint"| node_stats_api

click node_dashboard "https://github.com/kx1t/docker-commuterrail/blob/main/index.html"
click node_settings "https://github.com/kx1t/docker-commuterrail/blob/main/index.html"
click node_departures "https://github.com/kx1t/docker-commuterrail/blob/main/index.html"
click node_map_dialog "https://github.com/kx1t/docker-commuterrail/blob/main/index.html"
click node_cache_server "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_transit_modes "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_cache_lifecycle "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_upstream_fetch "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_snapshot_builder "https://github.com/kx1t/docker-commuterrail/blob/main/app/map_snapshot.py"
click node_diagnostics_view "https://github.com/kx1t/docker-commuterrail/blob/main/index.html"
click node_stats_api "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_stats_journal "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py"
click node_client_provenance "https://github.com/kx1t/docker-commuterrail/blob/main/app/server.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_dashboard,node_settings,node_departures,node_map_dialog toneBlue
class node_cache_server,node_transit_modes,node_cache_lifecycle,node_upstream_fetch,node_snapshot_builder toneAmber
class node_prim,node_mbta toneMint
class node_diagnostics_view,node_stats_api,node_stats_journal,node_client_provenance toneRose
class node_rider toneIndigo
```

## Components

### Browser dashboard

- [Departures dashboard](https://github.com/kx1t/docker-commuterrail/blob/main/index.html): `index.html`
- [Transit settings](https://github.com/kx1t/docker-commuterrail/blob/main/index.html): `index.html`
- [Departure selection](https://github.com/kx1t/docker-commuterrail/blob/main/index.html): `index.html`
- [Snapshot map dialog](https://github.com/kx1t/docker-commuterrail/blob/main/index.html): `index.html`

### Cache service

- [HTTP cache service](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Transit mode handling](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Cache and refresh](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Upstream data fetch](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Vehicle snapshot extraction](https://github.com/kx1t/docker-commuterrail/blob/main/app/map_snapshot.py): `app/map_snapshot.py`

### Transit data

- **Paris PRIM**
- **Boston MBTA**

### Cache diagnostics

- [Diagnostics view](https://github.com/kx1t/docker-commuterrail/blob/main/index.html): `index.html`
- [Stats endpoint](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Stats journal](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`
- [Client provenance](https://github.com/kx1t/docker-commuterrail/blob/main/app/server.py): `app/server.py`

### Other components

- **Rider**

## Connections

- Rider → Departures dashboard: views (evidence: `README.md`)
- Departures dashboard → Transit settings: opens (evidence: `README.md`)
- Transit settings → Departure selection: selects mode (evidence: `README.md`)
- Departures dashboard → HTTP cache service: requests departures (evidence: `README.md`)
- Departure selection → Transit mode handling: sends transit (evidence: `README.md`)
- HTTP cache service → Transit mode handling: routes request (evidence: `app/server.py`)
- HTTP cache service → Cache and refresh: gets or refreshes (evidence: `app/server.py`)
- Cache and refresh → Upstream data fetch: refreshes stale data (evidence: `README.md`)
- Upstream data fetch → Paris PRIM: fetches Paris data (evidence: `app/server.py`)
- Upstream data fetch → Boston MBTA: fetches Boston data (evidence: `app/server.py`)
- HTTP cache service → Vehicle snapshot extraction: builds snapshots (evidence: `app/server.py`)
- Departure selection → Snapshot map dialog: opens map (evidence: `README.md`)
- Snapshot map dialog → HTTP cache service: requests position (evidence: `README.md`)
- Rider → Diagnostics view: opens diagnostics (evidence: `README.md`)
- Diagnostics view → Stats endpoint: reads statistics (evidence: `README.md`)
- Stats endpoint → Stats journal: reads and records (evidence: `app/server.py`)
- Stats endpoint → Client provenance: reports clients (evidence: `README.md`)
- HTTP cache service → Stats endpoint: serves endpoint (evidence: `README.md`)
