- Python 60.9%
- TypeScript 29.9%
- JavaScript 3.7%
- CSS 2.7%
- HTML 2.3%
- Other 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- verifier round-trip test for a PAT before/after revocation; real bearer path test for token management - user row locked (FOR UPDATE) before the live-token cap check - OAuth connections report expires_at null (1 h access expiry isn't the connection's end); reserved client id raises RegistrationError - Settings: token rows show created date; reveal panel repeats the server URL + Bearer hint, clears when that token is revoked, and reports a failed clipboard write; field styles reuse ui/Pill fieldClasses Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> |
||
| .github/workflows | ||
| .impeccable | ||
| backend | ||
| docs/superpowers | ||
| frontend | ||
| raildata-sftp | ||
| .gitignore | ||
| CLAUDE.md | ||
| compose.yml | ||
| DESIGN.md | ||
| HANDOFF.md | ||
| PRODUCT.md | ||
| README.md | ||
Train Tracker
Train Tracker is a full-stack web app for monitoring UK railway services in real time. Add a train by headcode and see its live status, delays, current location, and per-stop calling points — glanceable enough to answer "is my train OK?" at a glance, with richer detail (timelines, delay history, disruption context) available for anyone who wants to dig in.
Features
- Add trains by headcode, Service UID, or station departure board search — with live status, delay, current location, and platform.
- Per-stop timelines showing booked vs. actual times all the way along a service's route.
- Recurring trains for a regular commute, with bank-holiday-aware exceptions.
- Journey planning — direct and interchange routes from the local timetable, with live delay data factored into whether a connection is actually catchable.
- Notifications via Discord DM, Telegram, and Web Push — delays, cancellations, boarding/arrival, off-route alerts.
- Punctuality stats and an archive of past journeys.
- Household view — see other household members' trains for today.
- Public share links for a single tracked train, no login required.
- Disruption dashboard (TfL + National Rail), when configured.
- Discord bot integration — slash commands, DM notifications, OAuth login.
Architecture
Caddy (TLS)
↓
FastAPI (Python 3.12, also serves the built React 18 + Vite SPA)
+ SQLAlchemy
↕ psycopg2
PostgreSQL 16
Live data comes primarily from a locally-ingested CIF full timetable feed (Rail Data Marketplace), overlaid with Darwin Push Port real-time movement events consumed continuously via Kafka — not the Realtime Trains (RTT) API, which is used only as a fallback when the local data has no match. See CLAUDE.md for the full data-pipeline design.
An MCP (Model Context Protocol) server is also exposed, so an AI assistant can look up live train status, search departures, plan journeys, and manage tracked trains on the user's behalf.
Running it
Requires Docker Compose. Copy .env.example (if present) or otherwise populate a .env file with the required credentials — see CLAUDE.md's Environment Variables section for the full list (database password, JWT secret, RTT/Darwin/NROD/Discord/Telegram/Web Push credentials, etc.).
docker compose up # start the full stack (db, backend, frontend, raildata-sftp)
docker compose build # rebuild images after a code change
The raildata-sftp service receives the daily CIF timetable push from Rail Data Marketplace; the backend watches for new files and ingests them automatically.
Frontend only
cd frontend
npm install
npm run dev # Vite dev server, proxies /api → localhost:8000
npm run build # TypeScript check + production build
Backend only
cd backend
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000
Contributing / development notes
See CLAUDE.md for the full architecture write-up, data pipeline design, backend/frontend file structure, and the conventions this codebase follows (timezone handling, sync-vs-async DB access, JSON column mutation, etc.) — required reading before making non-trivial changes.