# sahejpreet-glitch/train-track-codex architecture

> Architecture diagram of the GitHub repository sahejpreet-glitch/train-track-codex, 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/sahejpreet-glitch/train-track-codex
- Repository: https://github.com/sahejpreet-glitch/train-track-codex

## Overview

SETU AI provides passenger train tracking and probabilistic ETA explanations, alongside fleet and dispatch intelligence. The primary workflow is train-number search in the tracking UI, retrieval and normalization by the frontend service, backend aggregation of railway and weather data, prediction, then display of current status, route progress, confidence bounds, and delay causes. The README also documents telemetry, corridor mapping, fleet overview, station boards, dispatch solving, and feedback. Backend excerpts are partial, so links for documented but unsampled capabilities are limited to the API module rather than inferred internal call chains.

Main entry points: [`backend/main.py`](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/main.py) (FastAPI service), [`src/App.tsx`](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/App.tsx) (React application), [`src/pages/TrackTrainPage.tsx`](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/pages/TrackTrainPage.tsx) (Train tracking UI), [`src/services/trainService.ts`](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/services/trainService.ts) (Train data service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Passenger interfaces"]
  node_react_app["React application<br/>[App.tsx]"]
  node_track_ui["Train tracking UI<br/>[TrackTrainPage.tsx]"]
  node_train_service["Train data service<br/>[trainService.ts]"]
  node_static_dashboard["Simple dashboard<br/>[dashboard.html]"]
  node_feedback_ui["Feedback page<br/>[FeedbackPage.tsx]"]
  node_feedback_service["Feedback service<br/>[feedbackService.ts]"]
end

subgraph group_api["API and orchestration"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_railway["Railway intelligence"]
  node_railradar["RailRadar provider"]
  node_predictor["Delay predictor<br/>[ml_engine.py]"]
  node_route_sim["Route simulator<br/>[route_simulator.py]"]
end

subgraph group_integrations["External integrations"]
  node_weather["Weather integration<br/>[external_apis.py]"]
  node_gemini["Forecast explanation<br/>[gemini_service.py]"]
  node_email["Feedback delivery<br/>[email_service.py]"]
  node_railradar_api["RailRadar service"]
  node_weather_api["Weather service"]
  node_gemini_api["Gemini service"]
  node_email_provider["Email provider"]
end

node_passenger(("Passenger"))

node_passenger -->|"uses"| node_react_app
node_react_app -->|"renders"| node_track_ui
node_track_ui -->|"requests train data"| node_train_service
node_train_service -->|"fetches forecast and route"| node_api
node_static_dashboard -->|"calls dashboard APIs"| node_api
node_api -->|"requests railway data"| node_railradar
node_railradar -->|"fetches live and schedule data"| node_railradar_api
node_api -->|"requests weather data"| node_weather
node_weather -->|"fetches weather"| node_weather_api
node_api -->|"predicts delay"| node_predictor
node_api -->|"builds route telemetry"| node_route_sim
node_api -.->|"requests explanation"| node_gemini
node_gemini -.->|"generates explanation"| node_gemini_api
node_passenger -->|"submits feedback"| node_feedback_ui
node_feedback_ui -->|"sends submission"| node_feedback_service
node_feedback_service -->|"posts feedback"| node_api
node_api -->|"dispatches feedback"| node_email
node_email -->|"delivers email"| node_email_provider

click node_react_app "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/App.tsx"
click node_track_ui "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/pages/TrackTrainPage.tsx"
click node_train_service "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/services/trainService.ts"
click node_static_dashboard "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/dashboard.html"
click node_feedback_ui "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/pages/FeedbackPage.tsx"
click node_feedback_service "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/services/feedbackService.ts"
click node_api "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/main.py"
click node_railradar "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/railradar_service.py"
click node_predictor "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/ml_engine.py"
click node_route_sim "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/route_simulator.py"
click node_weather "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/external_apis.py"
click node_gemini "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/gemini_service.py"
click node_email "https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/email_service.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_react_app,node_track_ui,node_train_service,node_static_dashboard,node_feedback_ui,node_feedback_service toneBlue
class node_api toneAmber
class node_railradar,node_predictor,node_route_sim toneMint
class node_weather,node_gemini,node_email,node_railradar_api,node_weather_api,node_gemini_api,node_email_provider toneRose
class node_passenger toneIndigo
```

## Components

### Passenger interfaces

- [React application](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/App.tsx): `src/App.tsx`
- [Train tracking UI](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/pages/TrackTrainPage.tsx): `src/pages/TrackTrainPage.tsx`
- [Train data service](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/services/trainService.ts): `src/services/trainService.ts`
- [Simple dashboard](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/dashboard.html): `dashboard.html`
- [Feedback page](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/pages/FeedbackPage.tsx): `src/pages/FeedbackPage.tsx`
- [Feedback service](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/src/services/feedbackService.ts): `src/services/feedbackService.ts`

### API and orchestration

- [FastAPI service](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/main.py): `backend/main.py`

### Railway intelligence

- [RailRadar provider](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/railradar_service.py): `backend/railradar_service.py`
- [Delay predictor](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/ml_engine.py): `backend/ml_engine.py`
- [Route simulator](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/route_simulator.py): `backend/route_simulator.py`

### External integrations

- [Weather integration](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/external_apis.py): `backend/external_apis.py`
- [Forecast explanation](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/gemini_service.py): `backend/gemini_service.py`
- [Feedback delivery](https://github.com/sahejpreet-glitch/train-track-codex/blob/main/backend/email_service.py): `backend/email_service.py`
- **RailRadar service**
- **Weather service**
- **Gemini service**
- **Email provider**

### Other components

- **Passenger**

## Connections

- Passenger → React application: uses
- React application → Train tracking UI: renders
- Train tracking UI → Train data service: requests train data
- Train data service → FastAPI service: fetches forecast and route
- Simple dashboard → FastAPI service: calls dashboard APIs
- FastAPI service → RailRadar provider: requests railway data
- RailRadar provider → RailRadar service: fetches live and schedule data
- FastAPI service → Weather integration: requests weather data
- Weather integration → Weather service: fetches weather
- FastAPI service → Delay predictor: predicts delay
- FastAPI service → Route simulator: builds route telemetry
- FastAPI service → Forecast explanation: requests explanation
- Forecast explanation → Gemini service: generates explanation
- Passenger → Feedback page: submits feedback
- Feedback page → Feedback service: sends submission
- Feedback service → FastAPI service: posts feedback
- FastAPI service → Feedback delivery: dispatches feedback
- Feedback delivery → Email provider: delivers email