# hemampandey/railvia architecture

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

- Interactive diagram: https://gitdiagram.com/hemampandey/railvia
- Repository: https://github.com/hemampandey/railvia

## Overview

RailVia is a railway maintenance block-planning product: controllers use a web dashboard to view a plan that coordinates ENGG, TRD, and S&T work against train traffic, then manage approvals and completion/reporting. The documented planning path combines timetable-grounded or synthetic inputs, predictive criticality, and CP-SAT allocation; the API serves results and operational actions to the browser. The tree and excerpts support the main modules and API boundaries, but not every route’s internal wiring, so uncertain links are omitted.

Main entry points: [`src/api/app.py`](https://github.com/hemampandey/railvia/blob/main/src/api/app.py) (FastAPI service), [`web/lib/api.ts`](https://github.com/hemampandey/railvia/blob/main/web/lib/api.ts) (API client), [`src/adapters/hybrid.py`](https://github.com/hemampandey/railvia/blob/main/src/adapters/hybrid.py) (Grounded inputs), [`src/models/core.py`](https://github.com/hemampandey/railvia/blob/main/src/models/core.py) (Planning vocabulary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Operations dashboard"]
  node_dashboard_pages["Planner views"]
  node_auth_ui["Sign-in state<br/>[AuthProvider.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_planning_data["Planning data"]
  node_domain_models["Planning vocabulary<br/>[core.py]"]
  node_timetable_ingest["Timetable parsing<br/>[timetable.py]"]
  node_hybrid_adapter["Grounded inputs<br/>[hybrid.py]"]
  node_synthetic_generator["Synthetic inputs<br/>[synthetic.py]"]
end

subgraph group_planning_engine["Planning engine"]
  node_criticality["Urgency scoring<br/>[criticality.py]"]
  node_features["Risk features<br/>[features.py]"]
  node_optimizer["CP-SAT planner<br/>[model.py]"]
  node_replanner["Disruption replanner<br/>[replan.py]"]
  node_manual_baseline["Manual comparison<br/>[manual.py]"]
end

subgraph group_service_state["API and state"]
  node_api["FastAPI service<br/>[app.py]"]
  node_plan_cache["Plan cache<br/>[cache.py]"]
  node_store_auth["Token verification<br/>[auth.py]"]
  node_store_backend["Decision storage<br/>[supabase_store.py]"]
end

node_controller(("Railway controller"))
node_railradar["RailRadar timetable"]
node_supabase[("Supabase and Postgres")]

node_controller -->|"uses"| node_dashboard_pages
node_dashboard_pages -->|"requests data"| node_api_client
node_auth_ui -->|"fetches identity"| node_api_client
node_auth_ui -->|"signs in"| node_supabase
node_api_client -->|"calls API"| node_api
node_api -->|"checks plans"| node_plan_cache
node_api -->|"builds grounded input"| node_hybrid_adapter
node_api -->|"builds synthetic input"| node_synthetic_generator
node_railradar -.->|"supplies timetable"| node_timetable_ingest
node_timetable_ingest -->|"derives traffic"| node_hybrid_adapter
node_hybrid_adapter -->|"produces instance data"| node_domain_models
node_synthetic_generator -->|"produces instance data"| node_domain_models
node_api -->|"scores urgency"| node_criticality
node_criticality -->|"uses features"| node_features
node_api -->|"solves plan"| node_optimizer
node_optimizer -->|"reads instance"| node_domain_models
node_api -->|"replans disruptions"| node_replanner
node_api -->|"compares plans"| node_manual_baseline
node_api -->|"verifies caller"| node_store_auth
node_api -->|"reads and writes decisions"| node_store_backend
node_store_backend -->|"persists decisions"| node_supabase
node_store_auth -.->|"verifies signing keys"| node_supabase

click node_dashboard_pages "https://github.com/hemampandey/railvia/tree/main/web/app/(app)"
click node_auth_ui "https://github.com/hemampandey/railvia/blob/main/web/components/AuthProvider.tsx"
click node_api_client "https://github.com/hemampandey/railvia/blob/main/web/lib/api.ts"
click node_domain_models "https://github.com/hemampandey/railvia/blob/main/src/models/core.py"
click node_timetable_ingest "https://github.com/hemampandey/railvia/blob/main/src/ingest/timetable.py"
click node_hybrid_adapter "https://github.com/hemampandey/railvia/blob/main/src/adapters/hybrid.py"
click node_synthetic_generator "https://github.com/hemampandey/railvia/blob/main/src/generator/synthetic.py"
click node_criticality "https://github.com/hemampandey/railvia/blob/main/src/ml/criticality.py"
click node_features "https://github.com/hemampandey/railvia/blob/main/src/ml/features.py"
click node_optimizer "https://github.com/hemampandey/railvia/blob/main/src/optimiser/model.py"
click node_replanner "https://github.com/hemampandey/railvia/blob/main/src/optimiser/replan.py"
click node_manual_baseline "https://github.com/hemampandey/railvia/blob/main/src/baseline/manual.py"
click node_api "https://github.com/hemampandey/railvia/blob/main/src/api/app.py"
click node_plan_cache "https://github.com/hemampandey/railvia/blob/main/src/api/cache.py"
click node_store_auth "https://github.com/hemampandey/railvia/blob/main/src/store/auth.py"
click node_store_backend "https://github.com/hemampandey/railvia/blob/main/src/store/supabase_store.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_pages,node_auth_ui,node_api_client toneBlue
class node_domain_models,node_timetable_ingest,node_hybrid_adapter,node_synthetic_generator,node_supabase toneAmber
class node_criticality,node_features,node_optimizer,node_replanner,node_manual_baseline toneMint
class node_api,node_plan_cache,node_store_auth,node_store_backend toneRose
class node_controller,node_railradar toneIndigo
```

## Components

### Operations dashboard

- [Planner views](https://github.com/hemampandey/railvia/tree/main/web/app/(app)): `web/app/(app)`
- [Sign-in state](https://github.com/hemampandey/railvia/blob/main/web/components/AuthProvider.tsx): `web/components/AuthProvider.tsx`
- [API client](https://github.com/hemampandey/railvia/blob/main/web/lib/api.ts): `web/lib/api.ts`

### Planning data

- [Planning vocabulary](https://github.com/hemampandey/railvia/blob/main/src/models/core.py): `src/models/core.py`
- [Timetable parsing](https://github.com/hemampandey/railvia/blob/main/src/ingest/timetable.py): `src/ingest/timetable.py`
- [Grounded inputs](https://github.com/hemampandey/railvia/blob/main/src/adapters/hybrid.py): `src/adapters/hybrid.py`
- [Synthetic inputs](https://github.com/hemampandey/railvia/blob/main/src/generator/synthetic.py): `src/generator/synthetic.py`

### Planning engine

- [Urgency scoring](https://github.com/hemampandey/railvia/blob/main/src/ml/criticality.py): `src/ml/criticality.py`
- [Risk features](https://github.com/hemampandey/railvia/blob/main/src/ml/features.py): `src/ml/features.py`
- [CP-SAT planner](https://github.com/hemampandey/railvia/blob/main/src/optimiser/model.py): `src/optimiser/model.py`
- [Disruption replanner](https://github.com/hemampandey/railvia/blob/main/src/optimiser/replan.py): `src/optimiser/replan.py`
- [Manual comparison](https://github.com/hemampandey/railvia/blob/main/src/baseline/manual.py): `src/baseline/manual.py`

### API and state

- [FastAPI service](https://github.com/hemampandey/railvia/blob/main/src/api/app.py): `src/api/app.py`
- [Plan cache](https://github.com/hemampandey/railvia/blob/main/src/api/cache.py): `src/api/cache.py`
- [Token verification](https://github.com/hemampandey/railvia/blob/main/src/store/auth.py): `src/store/auth.py`
- [Decision storage](https://github.com/hemampandey/railvia/blob/main/src/store/supabase_store.py): `src/store/supabase_store.py`

### Other components

- **Railway controller**
- **RailRadar timetable**
- **Supabase and Postgres**

## Connections

- Railway controller → Planner views: uses
- Planner views → API client: requests data
- Sign-in state → API client: fetches identity
- Sign-in state → Supabase and Postgres: signs in
- API client → FastAPI service: calls API
- FastAPI service → Plan cache: checks plans
- FastAPI service → Grounded inputs: builds grounded input
- FastAPI service → Synthetic inputs: builds synthetic input
- RailRadar timetable → Timetable parsing: supplies timetable
- Timetable parsing → Grounded inputs: derives traffic
- Grounded inputs → Planning vocabulary: produces instance data
- Synthetic inputs → Planning vocabulary: produces instance data
- FastAPI service → Urgency scoring: scores urgency
- Urgency scoring → Risk features: uses features
- FastAPI service → CP-SAT planner: solves plan
- CP-SAT planner → Planning vocabulary: reads instance
- FastAPI service → Disruption replanner: replans disruptions
- FastAPI service → Manual comparison: compares plans
- FastAPI service → Token verification: verifies caller
- FastAPI service → Decision storage: reads and writes decisions
- Decision storage → Supabase and Postgres: persists decisions
- Token verification → Supabase and Postgres: verifies signing keys