# adi-tya-dev/rail_setu_sih architecture

> Architecture diagram of the GitHub repository adi-tya-dev/rail_setu_sih, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adi-tya-dev/rail_setu_sih
- Repository: https://github.com/adi-tya-dev/rail_setu_sih

## Overview

RailSetu is a railway operations platform for maintenance, train and asset visibility, conflict monitoring, simulation, and work-block planning. Users navigate operational views in the frontend; backend API routes serve those views, while the planning pipeline gathers maintenance tasks and available track windows, clusters work, scores packages, and optimizes assignments. A separate simulator-watcher and event-processing path publishes live updates. The source index and excerpts establish the main wiring; several UI-to-API and unsampled feature relationships are therefore left unconnected.

Main entry points: [`Backend/src/services/blockPlanning.service.js`](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/services/blockPlanning.service.js) (Block planning pipeline), [`frontend/src/App.jsx`](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/App.jsx) (App and navigation), [`Backend/src/app.js`](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/app.js) (Express API app), [`Backend/src/events/changeProcessor.js`](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/changeProcessor.js) (Change processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Operations UI"]
  node_app["App and navigation<br/>[App.jsx]"]
  node_ops_pages["Operations pages"]
  node_ml_page["ML planning view"]
  node_map_page["Railway map<br/>[RailwayMap.jsx]"]
  node_slots_page["Timetable slots<br/>[TimetableSlots.jsx]"]
  node_live_ui["Live event context"]
end

subgraph group_api["Backend API"]
  node_http_app["Express API app<br/>[app.js]"]
  node_api_routes["API route modules"]
  node_planning_controller["Planning controller"]
  node_integration_controller["Integration controller"]
  node_feature_services["Operational services"]
end

subgraph group_planning["Planning and simulation"]
  node_pipeline["Block planning pipeline"]
  node_clustering["Spatial clustering"]
  node_optimization["Window optimization"]
  node_ml_scoring["ML package scoring"]
  node_simulation["Simulation and rerouting"]
end

subgraph group_live["Live integrations"]
  node_watcher["Simulator watcher"]
  node_processor["Change processor<br/>[changeProcessor.js]"]
  node_sse["SSE connection manager<br/>[sseManager.js]"]
  node_simulators["Rail system simulators"]
end

subgraph group_data["Persistence and domain data"]
  node_prisma[("Prisma configuration<br/>[prisma.js]")]
  node_seed_data["Planning seed catalog"]
  node_network["Railway network data<br/>[railwayNetwork.js]"]
end

node_operator(("Rail operations user"))

node_operator -->|"uses"| node_app
node_app -->|"routes to"| node_ops_pages
node_app -->|"routes to"| node_ml_page
node_app -->|"routes to"| node_map_page
node_app -->|"routes to"| node_slots_page
node_http_app -->|"mounts"| node_api_routes
node_api_routes -->|"routes to"| node_planning_controller
node_api_routes -->|"routes to"| node_integration_controller
node_planning_controller -->|"invokes"| node_pipeline
node_planning_controller -->|"uses"| node_clustering
node_integration_controller -->|"invokes"| node_feature_services
node_integration_controller -->|"attaches stream"| node_sse
node_pipeline -->|"clusters tasks"| node_clustering
node_pipeline -->|"optimizes windows"| node_optimization
node_pipeline -->|"scores packages"| node_ml_scoring
node_pipeline -->|"fetches COA data"| node_simulators
node_pipeline -->|"reads tasks"| node_prisma
node_pipeline -->|"uses fallback data"| node_seed_data
node_simulation -->|"uses route data"| node_network
node_watcher -->|"polls sources"| node_simulators
node_processor -->|"broadcasts events"| node_sse
node_processor -->|"updates planning"| node_pipeline
node_live_ui -.->|"shows live updates"| node_operator
node_watcher -->|"emits requests"| node_processor
node_http_app -->|"starts watcher"| node_watcher
node_http_app -->|"starts processor"| node_processor
node_http_app -->|"starts heartbeat"| node_sse

click node_app "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/App.jsx"
click node_ops_pages "https://github.com/adi-tya-dev/rail_setu_sih/tree/main/frontend/src/pages"
click node_ml_page "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/BlockPlanningML.jsx"
click node_map_page "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/RailwayMap.jsx"
click node_slots_page "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/TimetableSlots.jsx"
click node_live_ui "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/contexts/LiveEventsContext.jsx"
click node_http_app "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/app.js"
click node_api_routes "https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/routes"
click node_planning_controller "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/controllers/blockPlanning.controller.js"
click node_integration_controller "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/controllers/integration.controller.js"
click node_feature_services "https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/services"
click node_pipeline "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/services/blockPlanning.service.js"
click node_clustering "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/clusteringEngine.js"
click node_optimization "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/optimizationEngine.js"
click node_ml_scoring "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/mlScoring.engine.js"
click node_simulation "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/simulation.engine.js"
click node_watcher "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/simulatorWatcher.js"
click node_processor "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/changeProcessor.js"
click node_sse "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/sseManager.js"
click node_simulators "https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/integration/simulators"
click node_prisma "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/config/prisma.js"
click node_seed_data "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/services/seedData.provider.js"
click node_network "https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/data/railwayNetwork.js"

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_app,node_ops_pages,node_ml_page,node_map_page,node_slots_page,node_live_ui,node_operator toneBlue
class node_http_app,node_api_routes,node_planning_controller,node_integration_controller,node_feature_services toneAmber
class node_pipeline,node_clustering,node_optimization,node_ml_scoring,node_simulation toneMint
class node_watcher,node_processor,node_sse,node_simulators toneRose
class node_prisma,node_seed_data,node_network toneIndigo
```

## Components

### Operations UI

- [App and navigation](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Operations pages](https://github.com/adi-tya-dev/rail_setu_sih/tree/main/frontend/src/pages): `frontend/src/pages`
- [ML planning view](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/BlockPlanningML.jsx): `frontend/src/pages/BlockPlanningML.jsx`
- [Railway map](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/RailwayMap.jsx): `frontend/src/pages/RailwayMap.jsx`
- [Timetable slots](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/pages/TimetableSlots.jsx): `frontend/src/pages/TimetableSlots.jsx`
- [Live event context](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/frontend/src/contexts/LiveEventsContext.jsx): `frontend/src/contexts/LiveEventsContext.jsx`

### Backend API

- [Express API app](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/app.js): `Backend/src/app.js`
- [API route modules](https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/routes): `Backend/src/routes`
- [Planning controller](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/controllers/blockPlanning.controller.js): `Backend/src/controllers/blockPlanning.controller.js`
- [Integration controller](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/controllers/integration.controller.js): `Backend/src/controllers/integration.controller.js`
- [Operational services](https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/services): `Backend/src/services`

### Planning and simulation

- [Block planning pipeline](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/services/blockPlanning.service.js): `Backend/src/services/blockPlanning.service.js`
- [Spatial clustering](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/clusteringEngine.js): `Backend/src/algorithms/clusteringEngine.js`
- [Window optimization](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/optimizationEngine.js): `Backend/src/algorithms/optimizationEngine.js`
- [ML package scoring](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/mlScoring.engine.js): `Backend/src/algorithms/mlScoring.engine.js`
- [Simulation and rerouting](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/algorithms/simulation.engine.js): `Backend/src/algorithms/simulation.engine.js`

### Live integrations

- [Simulator watcher](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/simulatorWatcher.js): `Backend/src/events/simulatorWatcher.js`
- [Change processor](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/changeProcessor.js): `Backend/src/events/changeProcessor.js`
- [SSE connection manager](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/events/sseManager.js): `Backend/src/events/sseManager.js`
- [Rail system simulators](https://github.com/adi-tya-dev/rail_setu_sih/tree/main/Backend/src/integration/simulators): `Backend/src/integration/simulators`

### Persistence and domain data

- [Prisma configuration](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/config/prisma.js): `Backend/src/config/prisma.js`
- [Planning seed catalog](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/services/seedData.provider.js): `Backend/src/services/seedData.provider.js`
- [Railway network data](https://github.com/adi-tya-dev/rail_setu_sih/blob/main/Backend/src/data/railwayNetwork.js): `Backend/src/data/railwayNetwork.js`

### Other components

- **Rail operations user**

## Connections

- Rail operations user → App and navigation: uses
- App and navigation → Operations pages: routes to (evidence: `frontend/src/App.jsx`)
- App and navigation → ML planning view: routes to (evidence: `frontend/src/App.jsx`)
- App and navigation → Railway map: routes to (evidence: `frontend/src/App.jsx`)
- App and navigation → Timetable slots: routes to (evidence: `frontend/src/App.jsx`)
- Express API app → API route modules: mounts (evidence: `Backend/src/app.js`)
- API route modules → Planning controller: routes to (evidence: `Backend/src/routes/blockPlanning.routes.js`)
- API route modules → Integration controller: routes to (evidence: `Backend/src/routes/integration.routes.js`)
- Planning controller → Block planning pipeline: invokes (evidence: `Backend/src/controllers/blockPlanning.controller.js`)
- Planning controller → Spatial clustering: uses (evidence: `Backend/src/controllers/blockPlanning.controller.js`)
- Integration controller → Operational services: invokes (evidence: `Backend/src/controllers/integration.controller.js`)
- Integration controller → SSE connection manager: attaches stream (evidence: `Backend/src/controllers/integration.controller.js`)
- Block planning pipeline → Spatial clustering: clusters tasks (evidence: `Backend/src/services/blockPlanning.service.js`)
- Block planning pipeline → Window optimization: optimizes windows (evidence: `Backend/src/services/blockPlanning.service.js`)
- Block planning pipeline → ML package scoring: scores packages (evidence: `Backend/src/services/blockPlanning.service.js`)
- Block planning pipeline → Rail system simulators: fetches COA data (evidence: `Backend/src/services/blockPlanning.service.js`)
- Block planning pipeline → Prisma configuration: reads tasks (evidence: `Backend/src/services/blockPlanning.service.js`)
- Block planning pipeline → Planning seed catalog: uses fallback data (evidence: `Backend/src/services/twoHorizonPlanning.service.js`)
- Simulation and rerouting → Railway network data: uses route data
- Simulator watcher → Rail system simulators: polls sources (evidence: `Backend/src/events/simulatorWatcher.js`)
- Change processor → SSE connection manager: broadcasts events (evidence: `Backend/src/events/changeProcessor.js`)
- Change processor → Block planning pipeline: updates planning (evidence: `Backend/src/events/changeProcessor.js`)
- Live event context → Rail operations user: shows live updates
- Simulator watcher → Change processor: emits requests (evidence: `Backend/server.js`)
- Express API app → Simulator watcher: starts watcher (evidence: `Backend/server.js`)
- Express API app → Change processor: starts processor (evidence: `Backend/server.js`)
- Express API app → SSE connection manager: starts heartbeat (evidence: `Backend/server.js`)
