# prakhar9642/railsync architecture

> Architecture diagram of the GitHub repository prakhar9642/railsync, 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/prakhar9642/railsync
- Repository: https://github.com/prakhar9642/railsync

## Overview

RailSync turns registered territory snapshots and maintenance demand into feasible, coordinated possessions, then supports comparison, lifecycle review, and disruption recovery. Users enter through the React planning workspace, which calls the FastAPI API; backend services load territory data and invoke optimization. The README documents the major optimizer layers and optional ML risk assistance, but sampled source does not show all their internal call sites, so uncertain wiring is omitted. No application database is used; plan lifecycle state is held in application memory.

Main entry points: [`backend/planning_service.py`](https://github.com/prakhar9642/railsync/blob/main/backend/planning_service.py) (Planning service), [`backend/main.py`](https://github.com/prakhar9642/railsync/blob/main/backend/main.py) (FastAPI routes), [`optimizer/optimizer.py`](https://github.com/prakhar9642/railsync/blob/main/optimizer/optimizer.py) (Optimizer orchestration), [`frontend/src/services/api.js`](https://github.com/prakhar9642/railsync/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_workspace["Planning workspace"]
  node_analysis["Plan analysis<br/>[AnalysisPage.jsx]"]
  node_scenario["Scenario lab<br/>[ScenarioLab.jsx]"]
  node_assistant["RailSaathi<br/>[RailSaathi.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_services["Backend services"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_planning["Planning service"]
  node_operations["Operations service"]
  node_recovery["Recovery service"]
  node_copilot["Copilot service<br/>[copilot_service.py]"]
end

subgraph group_optimization["Planning engine"]
  node_optimizer["Optimizer orchestration<br/>[optimizer.py]"]
  node_windows["Candidate windows"]
  node_feasibility["Feasibility checks<br/>[feasibility.py]"]
  node_resources["Resource constraints<br/>[resources.py]"]
  node_possessions["CP-SAT possessions<br/>[possessions.py]"]
  node_comparison["Plan comparison<br/>[comparison.py]"]
  node_recovery_engine["Recovery optimization<br/>[recovery.py]"]
end

subgraph group_inputs["Data and risk"]
  node_territories["Territory registry<br/>[territories.py]"]
  node_snapshots["Snapshot adapter<br/>[json_snapshot.py]"]
  node_risk["Risk inference<br/>[inference.py]"]
end

node_user(("Planner"))
node_gemini["Gemini API"]

node_user -->|"plans"| node_workspace
node_user -->|"reviews"| node_analysis
node_user -->|"tests scenarios"| node_scenario
node_workspace -->|"requests plans"| node_api_client
node_analysis -->|"requests analysis"| node_api_client
node_scenario -->|"requests recovery"| node_api_client
node_assistant -->|"requests assistance"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"delegates planning"| node_planning
node_api -->|"delegates lifecycle"| node_operations
node_api -->|"delegates recovery"| node_recovery
node_api -->|"delegates chat"| node_copilot
node_planning -->|"loads territory"| node_territories
node_territories -->|"reads snapshot"| node_snapshots
node_planning -->|"optimizes plan"| node_optimizer
node_optimizer -->|"builds windows"| node_windows
node_optimizer -->|"checks feasibility"| node_feasibility
node_optimizer -->|"checks resources"| node_resources
node_optimizer -->|"solves schedule"| node_possessions
node_planning -->|"compares baseline"| node_comparison
node_recovery -->|"reoptimizes work"| node_recovery_engine
node_planning -.->|"scores optional risk"| node_risk
node_copilot -->|"previews changes"| node_planning
node_copilot -->|"reads plan"| node_operations
node_copilot -.->|"generates response"| node_gemini

click node_workspace "https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/PlanningWorkspace.jsx"
click node_analysis "https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/AnalysisPage.jsx"
click node_scenario "https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/ScenarioLab.jsx"
click node_assistant "https://github.com/prakhar9642/railsync/blob/main/frontend/src/components/assistant/RailSaathi.jsx"
click node_api_client "https://github.com/prakhar9642/railsync/blob/main/frontend/src/services/api.js"
click node_api "https://github.com/prakhar9642/railsync/blob/main/backend/main.py"
click node_planning "https://github.com/prakhar9642/railsync/blob/main/backend/planning_service.py"
click node_operations "https://github.com/prakhar9642/railsync/blob/main/backend/operations_service.py"
click node_recovery "https://github.com/prakhar9642/railsync/blob/main/backend/recovery_service.py"
click node_copilot "https://github.com/prakhar9642/railsync/blob/main/backend/copilot_service.py"
click node_territories "https://github.com/prakhar9642/railsync/blob/main/data/territories.py"
click node_snapshots "https://github.com/prakhar9642/railsync/blob/main/data/adapters/json_snapshot.py"
click node_risk "https://github.com/prakhar9642/railsync/blob/main/ml/inference.py"
click node_optimizer "https://github.com/prakhar9642/railsync/blob/main/optimizer/optimizer.py"
click node_windows "https://github.com/prakhar9642/railsync/blob/main/optimizer/candidate_windows.py"
click node_feasibility "https://github.com/prakhar9642/railsync/blob/main/optimizer/feasibility.py"
click node_resources "https://github.com/prakhar9642/railsync/blob/main/optimizer/resources.py"
click node_possessions "https://github.com/prakhar9642/railsync/blob/main/optimizer/possessions.py"
click node_comparison "https://github.com/prakhar9642/railsync/blob/main/optimizer/comparison.py"
click node_recovery_engine "https://github.com/prakhar9642/railsync/blob/main/optimizer/recovery.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_workspace,node_analysis,node_scenario,node_assistant,node_api_client toneBlue
class node_api,node_planning,node_operations,node_recovery,node_copilot toneAmber
class node_optimizer,node_windows,node_feasibility,node_resources,node_possessions,node_comparison,node_recovery_engine,node_gemini toneMint
class node_territories,node_snapshots,node_risk toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Planning workspace](https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/PlanningWorkspace.jsx): `frontend/src/pages/PlanningWorkspace.jsx`
- [Plan analysis](https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/AnalysisPage.jsx): `frontend/src/pages/AnalysisPage.jsx`
- [Scenario lab](https://github.com/prakhar9642/railsync/blob/main/frontend/src/pages/ScenarioLab.jsx): `frontend/src/pages/ScenarioLab.jsx`
- [RailSaathi](https://github.com/prakhar9642/railsync/blob/main/frontend/src/components/assistant/RailSaathi.jsx): `frontend/src/components/assistant/RailSaathi.jsx`
- [API client](https://github.com/prakhar9642/railsync/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Backend services

- [FastAPI routes](https://github.com/prakhar9642/railsync/blob/main/backend/main.py): `backend/main.py`
- [Planning service](https://github.com/prakhar9642/railsync/blob/main/backend/planning_service.py): `backend/planning_service.py`
- [Operations service](https://github.com/prakhar9642/railsync/blob/main/backend/operations_service.py): `backend/operations_service.py`
- [Recovery service](https://github.com/prakhar9642/railsync/blob/main/backend/recovery_service.py): `backend/recovery_service.py`
- [Copilot service](https://github.com/prakhar9642/railsync/blob/main/backend/copilot_service.py): `backend/copilot_service.py`

### Planning engine

- [Optimizer orchestration](https://github.com/prakhar9642/railsync/blob/main/optimizer/optimizer.py): `optimizer/optimizer.py`
- [Candidate windows](https://github.com/prakhar9642/railsync/blob/main/optimizer/candidate_windows.py): `optimizer/candidate_windows.py`
- [Feasibility checks](https://github.com/prakhar9642/railsync/blob/main/optimizer/feasibility.py): `optimizer/feasibility.py`
- [Resource constraints](https://github.com/prakhar9642/railsync/blob/main/optimizer/resources.py): `optimizer/resources.py`
- [CP-SAT possessions](https://github.com/prakhar9642/railsync/blob/main/optimizer/possessions.py): `optimizer/possessions.py`
- [Plan comparison](https://github.com/prakhar9642/railsync/blob/main/optimizer/comparison.py): `optimizer/comparison.py`
- [Recovery optimization](https://github.com/prakhar9642/railsync/blob/main/optimizer/recovery.py): `optimizer/recovery.py`

### Data and risk

- [Territory registry](https://github.com/prakhar9642/railsync/blob/main/data/territories.py): `data/territories.py`
- [Snapshot adapter](https://github.com/prakhar9642/railsync/blob/main/data/adapters/json_snapshot.py): `data/adapters/json_snapshot.py`
- [Risk inference](https://github.com/prakhar9642/railsync/blob/main/ml/inference.py): `ml/inference.py`

### Other components

- **Planner**
- **Gemini API**

## Connections

- Planner → Planning workspace: plans
- Planner → Plan analysis: reviews
- Planner → Scenario lab: tests scenarios
- Planning workspace → API client: requests plans
- Plan analysis → API client: requests analysis
- Scenario lab → API client: requests recovery
- RailSaathi → API client: requests assistance
- API client → FastAPI routes: calls API
- FastAPI routes → Planning service: delegates planning
- FastAPI routes → Operations service: delegates lifecycle
- FastAPI routes → Recovery service: delegates recovery
- FastAPI routes → Copilot service: delegates chat
- Planning service → Territory registry: loads territory
- Territory registry → Snapshot adapter: reads snapshot
- Planning service → Optimizer orchestration: optimizes plan
- Optimizer orchestration → Candidate windows: builds windows
- Optimizer orchestration → Feasibility checks: checks feasibility
- Optimizer orchestration → Resource constraints: checks resources
- Optimizer orchestration → CP-SAT possessions: solves schedule
- Planning service → Plan comparison: compares baseline
- Recovery service → Recovery optimization: reoptimizes work
- Planning service → Risk inference: scores optional risk
- Copilot service → Planning service: previews changes
- Copilot service → Operations service: reads plan
- Copilot service → Gemini API: generates response