# ayush3038/rmos architecture

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

## Overview

RMOS is a railway maintenance decision-support platform: railway inputs are normalized and checked, mapped to canonical assets, assessed for risk and priority, constrained for safety, and optimized into candidate block plans. The frontend presents plans for human review; decisions are audited, while operational events can trigger replanning. The graph also includes simulation and knowledge retrieval capabilities. README documents the overall workflow; sampled service excerpts support several internal calls, but unsampled service wiring is represented only where documented.

Main entry points: [`backend/src/main/java/com/rmos/service/planning/PlanningService.java`](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/PlanningService.java) (Planning orchestration), [`frontend/src/services/api/client.ts`](https://github.com/ayush3038/rmos/blob/main/frontend/src/services/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/ayush3038/rmos/blob/main/frontend/src/App.tsx) (RMOS interface), [`backend/src/main/java/com/rmos/controller/decision/PlanDecisionController.java`](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/controller/decision/PlanDecisionController.java) (Human plan review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_frontend["RMOS interface<br/>[App.tsx]"]
  node_dashboard["Operations dashboard<br/>[Dashboard.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_ingest["Data and assessment"]
  node_integration["Integration and normalization"]
  node_freshness["Freshness checks"]
  node_asset_mapping["Canonical asset mapping"]
  node_risk["Asset risk assessment"]
  node_priority["Priority assessment"]
end

subgraph group_planning["Planning and decisions"]
  node_safety["Safety validation"]
  node_planning_api["Planning endpoint"]
  node_planning_service["Planning orchestration"]
  node_validation["Railway context validation"]
  node_optimizer["Block optimizer"]
  node_explanation["Plan explanation"]
  node_review["Human plan review"]
  node_decision["Decision processing"]
  node_audit["Decision audit"]
end

subgraph group_support["Operations and support"]
  node_events["Incident mapping"]
  node_replanning["Dynamic replanning"]
  node_simulator["Operational simulator"]
  node_scenario["Plan scenarios"]
  node_knowledge["Knowledge retrieval"]
end

subgraph group_platform["Backend platform"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_database[("PostgreSQL and pgvector")]
end

node_operator(("Railway personnel"))
node_sources(("Railway systems"))
node_nim["NVIDIA NIM"]

node_operator -->|"uses"| node_frontend
node_sources -->|"supplies data"| node_integration
node_frontend -->|"requests"| node_api_client
node_api_client -->|"calls REST"| node_planning_api
node_api_client -->|"submits review"| node_review
node_integration -->|"checks freshness"| node_freshness
node_freshness -->|"supports mapping"| node_asset_mapping
node_asset_mapping -->|"provides asset identity"| node_risk
node_planning_api -->|"requests plans"| node_planning_service
node_planning_service -->|"validates context"| node_validation
node_planning_service -->|"optimizes blocks"| node_optimizer
node_planning_service -->|"validates safety"| node_safety
node_planning_service -->|"uses risk inputs"| node_risk
node_planning_service -->|"uses priority inputs"| node_priority
node_planning_service -->|"stores plan runs"| node_database
node_planning_service -->|"requests explanation"| node_explanation
node_operator -->|"reviews plan"| node_review
node_review -->|"submits decision"| node_decision
node_decision -->|"audits decision"| node_audit
node_audit -->|"stores audit"| node_database
node_simulator -->|"maps generated incidents"| node_events
node_events -.->|"updates planning context"| node_replanning
node_replanning -->|"replans"| node_planning_service
node_scenario -->|"simulates request"| node_planning_service
node_dashboard -->|"renders"| node_frontend
node_knowledge -.->|"embeds queries"| node_nim
node_knowledge -->|"searches vectors"| node_database
node_explanation -.->|"generates explanations"| node_nim
node_auth -->|"reads users and audits"| node_database

click node_frontend "https://github.com/ayush3038/rmos/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/ayush3038/rmos/blob/main/frontend/src/components/rmos/dashboard/Dashboard.tsx"
click node_api_client "https://github.com/ayush3038/rmos/blob/main/frontend/src/services/api/client.ts"
click node_integration "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/SourceDataRecordService.java"
click node_freshness "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/DataFreshnessService.java"
click node_asset_mapping "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/CanonicalAssetMappingService.java"
click node_risk "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/risk/AssetRiskAssessmentService.java"
click node_priority "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/priority/PriorityAssessmentService.java"
click node_safety "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/safety/SafetyValidationService.java"
click node_planning_api "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/controller/planning/PlanningController.java"
click node_planning_service "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/PlanningService.java"
click node_validation "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/RailwayPlanningValidationService.java"
click node_optimizer "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/ORToolsCpSatOptimizer.java"
click node_explanation "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/ai/ExplanationService.java"
click node_review "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/controller/decision/PlanDecisionController.java"
click node_decision "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/decision/PlanDecisionService.java"
click node_audit "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/decision/PlanDecisionAuditService.java"
click node_events "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/integration/IncidentMappingService.java"
click node_replanning "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/replanning/DynamicReplanningService.java"
click node_simulator "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/simulator/service/SimulationEngine.java"
click node_scenario "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/scenario/ScenarioSimulationService.java"
click node_auth "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/auth/AuthService.java"
click node_knowledge "https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/knowledge/KnowledgeRetrievalService.java"

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_dashboard,node_api_client toneBlue
class node_integration,node_freshness,node_asset_mapping,node_risk,node_priority toneAmber
class node_safety,node_planning_api,node_planning_service,node_validation,node_optimizer,node_explanation,node_review,node_decision,node_audit toneMint
class node_events,node_replanning,node_simulator,node_scenario,node_knowledge toneRose
class node_auth,node_database,node_operator,node_sources,node_nim toneIndigo
```

## Components

### Operator interface

- [RMOS interface](https://github.com/ayush3038/rmos/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Operations dashboard](https://github.com/ayush3038/rmos/blob/main/frontend/src/components/rmos/dashboard/Dashboard.tsx): `frontend/src/components/rmos/dashboard/Dashboard.tsx`
- [API client](https://github.com/ayush3038/rmos/blob/main/frontend/src/services/api/client.ts): `frontend/src/services/api/client.ts`

### Data and assessment

- [Integration and normalization](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/SourceDataRecordService.java): `backend/src/main/java/com/rmos/service/SourceDataRecordService.java`
- [Freshness checks](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/DataFreshnessService.java): `backend/src/main/java/com/rmos/service/DataFreshnessService.java`
- [Canonical asset mapping](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/CanonicalAssetMappingService.java): `backend/src/main/java/com/rmos/service/CanonicalAssetMappingService.java`
- [Asset risk assessment](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/risk/AssetRiskAssessmentService.java): `backend/src/main/java/com/rmos/service/risk/AssetRiskAssessmentService.java`
- [Priority assessment](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/priority/PriorityAssessmentService.java): `backend/src/main/java/com/rmos/service/priority/PriorityAssessmentService.java`

### Planning and decisions

- [Safety validation](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/safety/SafetyValidationService.java): `backend/src/main/java/com/rmos/service/safety/SafetyValidationService.java`
- [Planning endpoint](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/controller/planning/PlanningController.java): `backend/src/main/java/com/rmos/controller/planning/PlanningController.java`
- [Planning orchestration](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/PlanningService.java): `backend/src/main/java/com/rmos/service/planning/PlanningService.java`
- [Railway context validation](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/RailwayPlanningValidationService.java): `backend/src/main/java/com/rmos/service/planning/RailwayPlanningValidationService.java`
- [Block optimizer](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/planning/ORToolsCpSatOptimizer.java): `backend/src/main/java/com/rmos/service/planning/ORToolsCpSatOptimizer.java`
- [Plan explanation](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/ai/ExplanationService.java): `backend/src/main/java/com/rmos/service/ai/ExplanationService.java`
- [Human plan review](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/controller/decision/PlanDecisionController.java): `backend/src/main/java/com/rmos/controller/decision/PlanDecisionController.java`
- [Decision processing](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/decision/PlanDecisionService.java): `backend/src/main/java/com/rmos/service/decision/PlanDecisionService.java`
- [Decision audit](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/decision/PlanDecisionAuditService.java): `backend/src/main/java/com/rmos/service/decision/PlanDecisionAuditService.java`

### Operations and support

- [Incident mapping](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/integration/IncidentMappingService.java): `backend/src/main/java/com/rmos/service/integration/IncidentMappingService.java`
- [Dynamic replanning](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/replanning/DynamicReplanningService.java): `backend/src/main/java/com/rmos/service/replanning/DynamicReplanningService.java`
- [Operational simulator](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/simulator/service/SimulationEngine.java): `backend/src/main/java/com/rmos/simulator/service/SimulationEngine.java`
- [Plan scenarios](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/scenario/ScenarioSimulationService.java): `backend/src/main/java/com/rmos/service/scenario/ScenarioSimulationService.java`
- [Knowledge retrieval](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/knowledge/KnowledgeRetrievalService.java): `backend/src/main/java/com/rmos/service/knowledge/KnowledgeRetrievalService.java`

### Backend platform

- [Authentication](https://github.com/ayush3038/rmos/blob/main/backend/src/main/java/com/rmos/service/auth/AuthService.java): `backend/src/main/java/com/rmos/service/auth/AuthService.java`
- **PostgreSQL and pgvector**

### Other components

- **Railway personnel**
- **Railway systems**
- **NVIDIA NIM**

## Connections

- Railway personnel → RMOS interface: uses
- Railway systems → Integration and normalization: supplies data
- RMOS interface → API client: requests
- API client → Planning endpoint: calls REST
- API client → Human plan review: submits review
- Integration and normalization → Freshness checks: checks freshness
- Freshness checks → Canonical asset mapping: supports mapping
- Canonical asset mapping → Asset risk assessment: provides asset identity
- Planning endpoint → Planning orchestration: requests plans
- Planning orchestration → Railway context validation: validates context
- Planning orchestration → Block optimizer: optimizes blocks
- Planning orchestration → Safety validation: validates safety
- Planning orchestration → Asset risk assessment: uses risk inputs
- Planning orchestration → Priority assessment: uses priority inputs
- Planning orchestration → PostgreSQL and pgvector: stores plan runs
- Planning orchestration → Plan explanation: requests explanation
- Railway personnel → Human plan review: reviews plan
- Human plan review → Decision processing: submits decision
- Decision processing → Decision audit: audits decision
- Decision audit → PostgreSQL and pgvector: stores audit
- Operational simulator → Incident mapping: maps generated incidents
- Incident mapping → Dynamic replanning: updates planning context
- Dynamic replanning → Planning orchestration: replans
- Plan scenarios → Planning orchestration: simulates request
- Operations dashboard → RMOS interface: renders
- Knowledge retrieval → NVIDIA NIM: embeds queries
- Knowledge retrieval → PostgreSQL and pgvector: searches vectors
- Plan explanation → NVIDIA NIM: generates explanations
- Authentication → PostgreSQL and pgvector: reads users and audits