# 143sanjay58/sih26028-eta-train architecture

> Architecture diagram of the GitHub repository 143sanjay58/sih26028-eta-train, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/143sanjay58/sih26028-eta-train
- Repository: https://github.com/143sanjay58/sih26028-eta-train

## Overview

RAILPULSE AI presents passenger and railway-operations interfaces over a FastAPI railway intelligence service. The principal workflow is train selection/tracking through live train state to ETA prediction and delay explanation, with operational branches for weather, congestion, alerts, station reports and simulation. The README documents these capabilities; some route/service internals are unsampled, so only documented or directly evidenced relationships are connected.

Main entry points: [`backend/app/main.py`](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/sih_eta/service.py`](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/sih_eta/service.py) (ETA service), [`backend/app/database/session.py`](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/database/session.py) (Railway database), [`frontend/src/App.tsx`](https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/App.tsx) (Role-based app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_frontend["Role-based app<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_eta_view["ETA experience<br/>[ETAEngine.tsx]"]
  node_operations_ui["Operations views<br/>[ControlRoom.tsx]"]
end

subgraph group_api["API and services"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_train_routes["Train endpoints<br/>[trains.py]"]
  node_prediction_routes["Prediction endpoints<br/>[predictions.py]"]
  node_train_service["Train service<br/>[train_service.py]"]
end

subgraph group_intelligence["Railway intelligence"]
  node_eta_service["ETA service<br/>[service.py]"]
  node_eta_engine["Dynamic ETA engine"]
  node_eta_model["ETA predictor<br/>[eta_predictor.py]"]
  node_ml_predictor["ML predictor<br/>[predictor.py]"]
  node_weather_service["Weather service<br/>[weather_service.py]"]
  node_congestion["Congestion service"]
end

subgraph group_operations["Operations and realtime"]
  node_alerts["Alert service<br/>[alert_service.py]"]
  node_simulation["Simulation engine<br/>[engine.py]"]
  node_websocket["WebSocket manager"]
  node_copilot["AI copilot reports"]
  node_ai_service["AI provider service<br/>[service.py]"]
end

subgraph group_data["Persistence"]
  node_database[("Railway database<br/>[session.py]")]
  node_train_models["Train and route models<br/>[train.py]"]
  node_station_model["Station model<br/>[station.py]"]
  node_weather_model["Weather model<br/>[weather.py]"]
end

node_passengers(("Passengers"))
node_staff(("Railway staff"))
node_weather_api["Open-Meteo"]
node_redis[("Redis cache")]

node_passengers -->|"use"| node_frontend
node_staff -->|"use"| node_frontend
node_frontend -->|"requests"| node_api_client
node_frontend -->|"routes to"| node_eta_view
node_frontend -->|"routes to"| node_operations_ui
node_api_client -->|"calls"| node_prediction_routes
node_api_client -.->|"calls"| node_train_routes
node_backend -->|"registers"| node_train_routes
node_backend -->|"registers"| node_prediction_routes
node_backend -->|"starts"| node_simulation
node_backend -->|"routes"| node_websocket
node_prediction_routes -.->|"dispatches"| node_eta_service
node_train_routes -.->|"dispatches"| node_train_service
node_eta_service -->|"loads train state"| node_train_service
node_eta_service -->|"predicts with"| node_eta_engine
node_eta_engine -->|"uses"| node_eta_model
node_eta_service -.->|"reads"| node_database
node_train_service -.->|"reads"| node_database
node_train_models -->|"maps to"| node_database
node_station_model -->|"maps to"| node_database
node_weather_model -.->|"maps to"| node_database
node_simulation -->|"writes positions"| node_database
node_eta_service -->|"loads positions"| node_train_models
node_eta_service -->|"resolves station"| node_station_model
node_weather_service -.->|"uses"| node_weather_model
node_weather_service -.->|"fetches weather"| node_weather_api
node_prediction_routes -.->|"uses"| node_ml_predictor
node_backend -.->|"exposes alerts"| node_alerts
node_backend -.->|"exposes congestion"| node_congestion
node_backend -.->|"exposes weather"| node_weather_service
node_backend -.->|"exposes copilot"| node_copilot
node_copilot -.->|"requests generation"| node_ai_service
node_backend -.->|"configured for"| node_redis
node_backend -->|"broadcasts simulation status"| node_websocket
node_operations_ui -.->|"receives updates"| node_websocket

click node_frontend "https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/services/api.ts"
click node_eta_view "https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/pages/ETAEngine.tsx"
click node_operations_ui "https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/pages/ControlRoom.tsx"
click node_backend "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/main.py"
click node_train_routes "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/api/routes/trains.py"
click node_prediction_routes "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/api/routes/predictions.py"
click node_train_service "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/train_service.py"
click node_eta_service "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/sih_eta/service.py"
click node_eta_engine "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/sih_eta/dynamic_eta_engine.py"
click node_eta_model "https://github.com/143sanjay58/sih26028-eta-train/blob/main/eta_predictor.py"
click node_ml_predictor "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/ml/predictor.py"
click node_weather_service "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/weather_service.py"
click node_congestion "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/congestion_service.py"
click node_alerts "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/alert_service.py"
click node_simulation "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/simulation/engine.py"
click node_websocket "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/realtime/websocket_manager.py"
click node_copilot "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/copilot_report_service.py"
click node_ai_service "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/ai/service.py"
click node_database "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/database/session.py"
click node_train_models "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/train.py"
click node_station_model "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/station.py"
click node_weather_model "https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/weather.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_frontend,node_api_client,node_eta_view,node_operations_ui toneBlue
class node_backend,node_train_routes,node_prediction_routes,node_train_service,node_redis toneAmber
class node_eta_service,node_eta_engine,node_eta_model,node_ml_predictor,node_weather_service,node_congestion toneMint
class node_alerts,node_simulation,node_websocket,node_copilot,node_ai_service toneRose
class node_database,node_train_models,node_station_model,node_weather_model,node_passengers,node_staff,node_weather_api toneIndigo
```

## Components

### User interfaces

- [Role-based app](https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [ETA experience](https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/pages/ETAEngine.tsx): `frontend/src/pages/ETAEngine.tsx`
- [Operations views](https://github.com/143sanjay58/sih26028-eta-train/blob/main/frontend/src/pages/ControlRoom.tsx): `frontend/src/pages/ControlRoom.tsx`

### API and services

- [FastAPI application](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/main.py): `backend/app/main.py`
- [Train endpoints](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/api/routes/trains.py): `backend/app/api/routes/trains.py`
- [Prediction endpoints](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/api/routes/predictions.py): `backend/app/api/routes/predictions.py`
- [Train service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/train_service.py): `backend/app/services/train_service.py`

### Railway intelligence

- [ETA service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/sih_eta/service.py): `backend/app/sih_eta/service.py`
- [Dynamic ETA engine](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/sih_eta/dynamic_eta_engine.py): `backend/app/sih_eta/dynamic_eta_engine.py`
- [ETA predictor](https://github.com/143sanjay58/sih26028-eta-train/blob/main/eta_predictor.py): `eta_predictor.py`
- [ML predictor](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/ml/predictor.py): `backend/app/ml/predictor.py`
- [Weather service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Congestion service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/congestion_service.py): `backend/app/services/congestion_service.py`

### Operations and realtime

- [Alert service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Simulation engine](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/simulation/engine.py): `backend/app/simulation/engine.py`
- [WebSocket manager](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/realtime/websocket_manager.py): `backend/app/realtime/websocket_manager.py`
- [AI copilot reports](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/copilot_report_service.py): `backend/app/services/copilot_report_service.py`
- [AI provider service](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/services/ai/service.py): `backend/app/services/ai/service.py`

### Persistence

- [Railway database](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Train and route models](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/train.py): `backend/app/models/train.py`
- [Station model](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/station.py): `backend/app/models/station.py`
- [Weather model](https://github.com/143sanjay58/sih26028-eta-train/blob/main/backend/app/models/weather.py): `backend/app/models/weather.py`

### Other components

- **Passengers**
- **Railway staff**
- **Open-Meteo**
- **Redis cache**

## Connections

- Passengers → Role-based app: use
- Railway staff → Role-based app: use
- Role-based app → API client: requests
- Role-based app → ETA experience: routes to (evidence: `frontend/src/App.tsx`)
- Role-based app → Operations views: routes to (evidence: `frontend/src/App.tsx`)
- API client → Prediction endpoints: calls
- API client → Train endpoints: calls
- FastAPI application → Train endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Prediction endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Simulation engine: starts (evidence: `backend/app/main.py`)
- FastAPI application → WebSocket manager: routes (evidence: `backend/app/main.py`)
- Prediction endpoints → ETA service: dispatches
- Train endpoints → Train service: dispatches
- ETA service → Train service: loads train state (evidence: `backend/app/sih_eta/service.py`)
- ETA service → Dynamic ETA engine: predicts with (evidence: `backend/app/sih_eta/service.py`)
- Dynamic ETA engine → ETA predictor: uses (evidence: `backend/app/sih_eta/dynamic_eta_engine.py`)
- ETA service → Railway database: reads
- Train service → Railway database: reads
- Train and route models → Railway database: maps to (evidence: `backend/app/models/train.py`)
- Station model → Railway database: maps to (evidence: `backend/app/models/station.py`)
- Weather model → Railway database: maps to (evidence: `backend/app/models/weather.py`)
- Simulation engine → Railway database: writes positions (evidence: `backend/app/simulation/engine.py`)
- ETA service → Train and route models: loads positions (evidence: `backend/app/sih_eta/service.py`)
- ETA service → Station model: resolves station (evidence: `backend/app/sih_eta/service.py`)
- Weather service → Weather model: uses (evidence: `backend/app/services/weather_service.py`)
- Weather service → Open-Meteo: fetches weather
- Prediction endpoints → ML predictor: uses
- FastAPI application → Alert service: exposes alerts
- FastAPI application → Congestion service: exposes congestion
- FastAPI application → Weather service: exposes weather
- FastAPI application → AI copilot reports: exposes copilot (evidence: `backend/app/main.py`)
- AI copilot reports → AI provider service: requests generation
- FastAPI application → Redis cache: configured for
- FastAPI application → WebSocket manager: broadcasts simulation status (evidence: `backend/app/main.py`)
- Operations views → WebSocket manager: receives updates
