# hostel1359-source/trustos architecture

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

- Interactive diagram: https://gitdiagram.com/hostel1359-source/trustos
- Repository: https://github.com/hostel1359-source/trustos

## Overview

TRUSTOS is a Vizag urban-flooding digital twin: operators run a deterministic scenario or adjust simulated conditions, then follow source trust, detected conflicts, flood predictions and recommended actions on a live map. The React client combines backend event updates with city intelligence and presents them through map, alert, camera and analysis panels; route planning assesses exposure to scenario incidents. The FastAPI service exposes REST and WebSocket interfaces, while its documented intelligence stages cover trust, conflict, prediction and explanation. Backend orchestration details are only partly sampled, so links between those stages follow the documented architecture; optional live weather is separate from simulated telemetry.

Main entry points: [`frontend/src/components/MapPage.tsx`](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/MapPage.tsx) (City dashboard), [`backend/services/demo_scenario.py`](https://github.com/hostel1359-source/trustos/blob/main/backend/services/demo_scenario.py) (Demo scenario), [`backend/main.py`](https://github.com/hostel1359-source/trustos/blob/main/backend/main.py) (FastAPI service), [`frontend/src/hooks/useDemoMode.ts`](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useDemoMode.ts) (Demo control hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Operator interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_map_page["City dashboard<br/>[MapPage.tsx]"]
  node_city_map["City map<br/>[CityMap.tsx]"]
  node_cesium_map["3D map<br/>[CesiumMap.tsx]"]
  node_camera_panel["Camera panel<br/>[CameraPanel.tsx]"]
  node_city_alerts["City alerts<br/>[CityAlerts.tsx]"]
  node_prediction_panel["Prediction panel"]
  node_conflict_panel["Reality conflicts"]
  node_trust_panel["Trust scores"]
  node_route_planner["Route planner<br/>[RoutePlanner.tsx]"]
  node_demo_controls["Scenario controls"]
end

subgraph group_frontend_state["Client state and feeds"]
  node_demo_hook["Demo control hook<br/>[useDemoMode.ts]"]
  node_ws_hook["WebSocket hook<br/>[useWebSocket.ts]"]
  node_city_hook["City intelligence hook"]
  node_store["Client state<br/>[useTrustosStore.ts]"]
  node_route_risk["Route exposure<br/>[routeRisk.ts]"]
end

subgraph group_backend["Backend intelligence"]
  node_api["FastAPI service<br/>[main.py]"]
  node_mobile_api["Mobile API<br/>[mobile_api.py]"]
  node_demo_scenario["Demo scenario<br/>[demo_scenario.py]"]
  node_trust_engine["Trust scoring<br/>[trust_engine.py]"]
  node_conflict_detector["Conflict detection"]
  node_prediction_engine["Flood prediction"]
  node_llm_reasoning["Situation explanation<br/>[llm_reasoning.py]"]
  node_ws_manager["WebSocket broadcast<br/>[manager.py]"]
end

subgraph group_data["City context"]
  node_city_data["Vizag context data"]
end

node_operator(("City operator"))
node_weather_service["Open-Meteo"]

node_operator -->|"uses dashboard"| node_map_page
node_app -->|"renders"| node_map_page
node_app -->|"opens stream"| node_ws_hook
node_map_page -->|"presents map"| node_city_map
node_map_page -->|"presents 3D"| node_cesium_map
node_map_page -->|"presents cameras"| node_camera_panel
node_map_page -->|"presents alerts"| node_city_alerts
node_map_page -->|"presents forecast"| node_prediction_panel
node_map_page -->|"presents conflicts"| node_conflict_panel
node_map_page -->|"presents scores"| node_trust_panel
node_map_page -->|"offers routing"| node_route_planner
node_map_page -->|"offers controls"| node_demo_controls
node_demo_controls -->|"controls scenario"| node_demo_hook
node_demo_hook -->|"starts or stops"| node_api
node_demo_hook -->|"posts changes"| node_api
node_demo_hook -->|"updates local state"| node_store
node_ws_hook -->|"connects stream"| node_api
node_api -->|"registers and broadcasts"| node_ws_manager
node_ws_hook -->|"dispatches messages"| node_store
node_city_hook -->|"reads intelligence"| node_store
node_city_hook -->|"fetches zones"| node_mobile_api
node_mobile_api -->|"reads city context"| node_city_data
node_city_hook -.->|"fetches weather"| node_weather_service
node_route_planner -->|"assesses exposure"| node_route_risk
node_route_risk -->|"uses incident context"| node_city_data
node_api -->|"starts scenario"| node_demo_scenario
node_demo_scenario -->|"broadcasts updates"| node_ws_manager
node_demo_scenario -->|"scores sources"| node_trust_engine
node_demo_scenario -->|"checks conflicts"| node_conflict_detector
node_demo_scenario -->|"predicts flooding"| node_prediction_engine
node_demo_scenario -->|"explains situation"| node_llm_reasoning
node_api -->|"recalculates trust"| node_trust_engine
node_trust_engine -->|"provides trust scores"| node_conflict_detector
node_conflict_detector -->|"provides conflict state"| node_prediction_engine
node_prediction_engine -->|"provides prediction"| node_llm_reasoning

click node_app "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/App.tsx"
click node_map_page "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/MapPage.tsx"
click node_city_map "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CityMap.tsx"
click node_cesium_map "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CesiumMap.tsx"
click node_camera_panel "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CameraPanel.tsx"
click node_city_alerts "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CityAlerts.tsx"
click node_prediction_panel "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/PredictionPanel.tsx"
click node_conflict_panel "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/RealityConflict.tsx"
click node_trust_panel "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/TrustScorePanel.tsx"
click node_route_planner "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/RoutePlanner.tsx"
click node_demo_controls "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/SimulationControls.tsx"
click node_demo_hook "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useDemoMode.ts"
click node_ws_hook "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_city_hook "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useCityIntelligence.ts"
click node_store "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/store/useTrustosStore.ts"
click node_api "https://github.com/hostel1359-source/trustos/blob/main/backend/main.py"
click node_mobile_api "https://github.com/hostel1359-source/trustos/blob/main/backend/routes/mobile_api.py"
click node_demo_scenario "https://github.com/hostel1359-source/trustos/blob/main/backend/services/demo_scenario.py"
click node_trust_engine "https://github.com/hostel1359-source/trustos/blob/main/backend/services/trust_engine.py"
click node_conflict_detector "https://github.com/hostel1359-source/trustos/blob/main/backend/services/conflict_detector.py"
click node_prediction_engine "https://github.com/hostel1359-source/trustos/blob/main/backend/services/prediction_engine.py"
click node_llm_reasoning "https://github.com/hostel1359-source/trustos/blob/main/backend/services/llm_reasoning.py"
click node_ws_manager "https://github.com/hostel1359-source/trustos/blob/main/backend/websocket/manager.py"
click node_city_data "https://github.com/hostel1359-source/trustos/tree/main/backend/data"
click node_route_risk "https://github.com/hostel1359-source/trustos/blob/main/frontend/src/utils/routeRisk.ts"

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_map_page,node_city_map,node_cesium_map,node_camera_panel,node_city_alerts,node_prediction_panel,node_conflict_panel,node_trust_panel,node_route_planner,node_demo_controls toneBlue
class node_demo_hook,node_ws_hook,node_city_hook,node_store,node_route_risk toneAmber
class node_api,node_mobile_api,node_demo_scenario,node_trust_engine,node_conflict_detector,node_prediction_engine,node_llm_reasoning,node_ws_manager toneMint
class node_city_data toneRose
class node_operator,node_weather_service toneIndigo
```

## Components

### Operator interface

- [App shell](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [City dashboard](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/MapPage.tsx): `frontend/src/components/MapPage.tsx`
- [City map](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CityMap.tsx): `frontend/src/components/CityMap.tsx`
- [3D map](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CesiumMap.tsx): `frontend/src/components/CesiumMap.tsx`
- [Camera panel](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CameraPanel.tsx): `frontend/src/components/CameraPanel.tsx`
- [City alerts](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/CityAlerts.tsx): `frontend/src/components/CityAlerts.tsx`
- [Prediction panel](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/PredictionPanel.tsx): `frontend/src/components/PredictionPanel.tsx`
- [Reality conflicts](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/RealityConflict.tsx): `frontend/src/components/RealityConflict.tsx`
- [Trust scores](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/TrustScorePanel.tsx): `frontend/src/components/TrustScorePanel.tsx`
- [Route planner](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/RoutePlanner.tsx): `frontend/src/components/RoutePlanner.tsx`
- [Scenario controls](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/components/SimulationControls.tsx): `frontend/src/components/SimulationControls.tsx`

### Client state and feeds

- [Demo control hook](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useDemoMode.ts): `frontend/src/hooks/useDemoMode.ts`
- [WebSocket hook](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`
- [City intelligence hook](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/hooks/useCityIntelligence.ts): `frontend/src/hooks/useCityIntelligence.ts`
- [Client state](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/store/useTrustosStore.ts): `frontend/src/store/useTrustosStore.ts`
- [Route exposure](https://github.com/hostel1359-source/trustos/blob/main/frontend/src/utils/routeRisk.ts): `frontend/src/utils/routeRisk.ts`

### Backend intelligence

- [FastAPI service](https://github.com/hostel1359-source/trustos/blob/main/backend/main.py): `backend/main.py`
- [Mobile API](https://github.com/hostel1359-source/trustos/blob/main/backend/routes/mobile_api.py): `backend/routes/mobile_api.py`
- [Demo scenario](https://github.com/hostel1359-source/trustos/blob/main/backend/services/demo_scenario.py): `backend/services/demo_scenario.py`
- [Trust scoring](https://github.com/hostel1359-source/trustos/blob/main/backend/services/trust_engine.py): `backend/services/trust_engine.py`
- [Conflict detection](https://github.com/hostel1359-source/trustos/blob/main/backend/services/conflict_detector.py): `backend/services/conflict_detector.py`
- [Flood prediction](https://github.com/hostel1359-source/trustos/blob/main/backend/services/prediction_engine.py): `backend/services/prediction_engine.py`
- [Situation explanation](https://github.com/hostel1359-source/trustos/blob/main/backend/services/llm_reasoning.py): `backend/services/llm_reasoning.py`
- [WebSocket broadcast](https://github.com/hostel1359-source/trustos/blob/main/backend/websocket/manager.py): `backend/websocket/manager.py`

### City context

- [Vizag context data](https://github.com/hostel1359-source/trustos/tree/main/backend/data): `backend/data`

### Other components

- **City operator**
- **Open-Meteo**

## Connections

- City operator → City dashboard: uses dashboard
- App shell → City dashboard: renders
- App shell → WebSocket hook: opens stream
- City dashboard → City map: presents map
- City dashboard → 3D map: presents 3D
- City dashboard → Camera panel: presents cameras
- City dashboard → City alerts: presents alerts
- City dashboard → Prediction panel: presents forecast
- City dashboard → Reality conflicts: presents conflicts
- City dashboard → Trust scores: presents scores
- City dashboard → Route planner: offers routing
- City dashboard → Scenario controls: offers controls
- Scenario controls → Demo control hook: controls scenario
- Demo control hook → FastAPI service: starts or stops
- Demo control hook → FastAPI service: posts changes
- Demo control hook → Client state: updates local state
- WebSocket hook → FastAPI service: connects stream
- FastAPI service → WebSocket broadcast: registers and broadcasts
- WebSocket hook → Client state: dispatches messages
- City intelligence hook → Client state: reads intelligence
- City intelligence hook → Mobile API: fetches zones
- Mobile API → Vizag context data: reads city context
- City intelligence hook → Open-Meteo: fetches weather
- Route planner → Route exposure: assesses exposure
- Route exposure → Vizag context data: uses incident context
- FastAPI service → Demo scenario: starts scenario
- Demo scenario → WebSocket broadcast: broadcasts updates
- Demo scenario → Trust scoring: scores sources
- Demo scenario → Conflict detection: checks conflicts
- Demo scenario → Flood prediction: predicts flooding
- Demo scenario → Situation explanation: explains situation
- FastAPI service → Trust scoring: recalculates trust
- Trust scoring → Conflict detection: provides trust scores
- Conflict detection → Flood prediction: provides conflict state
- Flood prediction → Situation explanation: provides prediction