# umesh-369/skygaurd-ai architecture

> Architecture diagram of the GitHub repository umesh-369/skygaurd-ai, 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/umesh-369/skygaurd-ai
- Repository: https://github.com/umesh-369/skygaurd-ai

## Overview

SkyGuard AI monitors automatic weather-station telemetry, detects sensor faults and communications failures, estimates corrections, and assesses regional hazards. Its main workflow runs through a React dashboard and FastAPI backend: simulated or station readings are evaluated, anomalies may be imputed and recorded, and risk context is broadcast to the interface. The README also documents historical-data replay, spatial consensus, degradation monitoring, reports, and operational recommendations. Several of those subsystems are present in the tree but were not sampled, so their links are shown as unverified rather than inferred calls.

Main entry points: [`backend/main.py`](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/main.py) (FastAPI Application), [`frontend/src/App.tsx`](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/App.tsx) (Web App), [`frontend/src/store/useSkyGuardStore.ts`](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/store/useSkyGuardStore.ts) (UI State and API), [`backend/api/routers/simulator.py`](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/api/routers/simulator.py) (Simulator Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Dashboard"]
  node_app["Web App<br/>[App.tsx]"]
  node_store["UI State and API"]
  node_dashboard["Dashboard and Analytics<br/>[DashboardPage.tsx]"]
  node_anomalies_ui["Anomaly Views<br/>[AnomaliesPage.tsx]"]
  node_sim_ui["Fault Simulator UI"]
end

subgraph group_runtime["Telemetry Runtime"]
  node_api["FastAPI Application<br/>[main.py]"]
  node_sim_routes["Simulator Routes<br/>[simulator.py]"]
  node_sim_service["AWS Simulator Service"]
  node_aws_sim["Virtual Station Mesh<br/>[aws_simulator.py]"]
  node_comm["Communications Monitor<br/>[comm_monitor.py]"]
  node_ws["WebSocket Broadcast<br/>[ws_manager.py]"]
end

subgraph group_diagnostics["Sensor Diagnostics"]
  node_detector["Tier 1 Detector"]
  node_ml_detector["Isolation Forest"]
  node_features["Feature Extraction"]
  node_shap["SHAP Explanations<br/>[shap_service.py]"]
  node_imputer["Value Imputation<br/>[imputer_service.py]"]
  node_spatial["Spatial Consensus"]
  node_degradation["Degradation Watchdog"]
end

subgraph group_hazards["Hazards and Response"]
  node_incidents["Incident Lifecycle"]
  node_risk["Tier 2 Hazard Risk<br/>[tier2_risk.py]"]
  node_weather["Weather Context<br/>[weather_service.py]"]
  node_recommend["Response Recommendations"]
  node_reports["Incident Reports<br/>[report_service.py]"]
end

subgraph group_data["State and Integrations"]
  node_database[("MongoDB Repositories")]
  node_historical["Historical Climate Data<br/>[data_loader.py]"]
  node_replay["Climate Replay Adapter"]
end

node_operator(("Operator"))

node_operator -.->|"uses"| node_app
node_app -->|"loads and connects"| node_store
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_anomalies_ui
node_app -.->|"renders"| node_sim_ui
node_store -->|"requests data"| node_api
node_api -->|"mounts routers"| node_sim_routes
node_sim_routes -->|"dispatches"| node_sim_service
node_sim_service -->|"delegates simulation"| node_aws_sim
node_api -->|"evaluates readings"| node_detector
node_detector -->|"delegates inference"| node_ml_detector
node_ml_detector -->|"uses features"| node_features
node_api -->|"requests correction"| node_imputer
node_api -->|"records anomalies"| node_incidents
node_api -->|"calculates risk"| node_risk
node_api -->|"fetches context"| node_weather
node_api -.->|"broadcasts updates"| node_ws
node_api -.->|"monitors telemetry"| node_comm
node_api -.->|"explains detections"| node_shap
node_api -.->|"checks neighbors"| node_spatial
node_api -.->|"monitors sensor health"| node_degradation
node_incidents -.->|"persists anomalies"| node_database
node_api -.->|"creates response actions"| node_recommend
node_api -.->|"serves reports"| node_reports
node_historical -.->|"supplies climate records"| node_replay
node_store -.->|"receives live events"| node_ws

click node_app "https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/App.tsx"
click node_store "https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/store/useSkyGuardStore.ts"
click node_dashboard "https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_anomalies_ui "https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/pages/AnomaliesPage.tsx"
click node_sim_ui "https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/components/SimulatorStudio.tsx"
click node_api "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/main.py"
click node_sim_routes "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/api/routers/simulator.py"
click node_sim_service "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/simulator/simulator_service.py"
click node_aws_sim "https://github.com/umesh-369/skygaurd-ai/blob/main/simulator/aws_simulator.py"
click node_comm "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/telemetry/comm_monitor.py"
click node_detector "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/anomaly_detection/detector_service.py"
click node_ml_detector "https://github.com/umesh-369/skygaurd-ai/blob/main/ml/anomaly_detector.py"
click node_features "https://github.com/umesh-369/skygaurd-ai/blob/main/ml/feature_extractor.py"
click node_shap "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/shap_service.py"
click node_imputer "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/imputer_service.py"
click node_spatial "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/risk_engine/spatial_consensus.py"
click node_degradation "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/degradation_service.py"
click node_incidents "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/incidents/incident_service.py"
click node_risk "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/risk_engine/tier2_risk.py"
click node_weather "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/integrations/weather/weather_service.py"
click node_recommend "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/recommendations/recommendation_service.py"
click node_reports "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/reports/report_service.py"
click node_ws "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/api/websocket/ws_manager.py"
click node_database "https://github.com/umesh-369/skygaurd-ai/tree/main/backend/database/repositories"
click node_historical "https://github.com/umesh-369/skygaurd-ai/blob/main/ml/data_loader.py"
click node_replay "https://github.com/umesh-369/skygaurd-ai/blob/main/backend/integrations/datasets/data_loader_adapter.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_app,node_store,node_dashboard,node_anomalies_ui,node_sim_ui toneBlue
class node_api,node_sim_routes,node_sim_service,node_aws_sim,node_comm,node_ws toneAmber
class node_detector,node_ml_detector,node_features,node_shap,node_imputer,node_spatial,node_degradation toneMint
class node_incidents,node_risk,node_weather,node_recommend,node_reports toneRose
class node_database,node_historical,node_replay,node_operator toneIndigo
```

## Components

### Dashboard

- [Web App](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [UI State and API](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/store/useSkyGuardStore.ts): `frontend/src/store/useSkyGuardStore.ts`
- [Dashboard and Analytics](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Anomaly Views](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/pages/AnomaliesPage.tsx): `frontend/src/pages/AnomaliesPage.tsx`
- [Fault Simulator UI](https://github.com/umesh-369/skygaurd-ai/blob/main/frontend/src/components/SimulatorStudio.tsx): `frontend/src/components/SimulatorStudio.tsx`

### Telemetry Runtime

- [FastAPI Application](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/main.py): `backend/main.py`
- [Simulator Routes](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/api/routers/simulator.py): `backend/api/routers/simulator.py`
- [AWS Simulator Service](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/simulator/simulator_service.py): `backend/simulator/simulator_service.py`
- [Virtual Station Mesh](https://github.com/umesh-369/skygaurd-ai/blob/main/simulator/aws_simulator.py): `simulator/aws_simulator.py`
- [Communications Monitor](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/telemetry/comm_monitor.py): `backend/telemetry/comm_monitor.py`
- [WebSocket Broadcast](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/api/websocket/ws_manager.py): `backend/api/websocket/ws_manager.py`

### Sensor Diagnostics

- [Tier 1 Detector](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/anomaly_detection/detector_service.py): `backend/anomaly_detection/detector_service.py`
- [Isolation Forest](https://github.com/umesh-369/skygaurd-ai/blob/main/ml/anomaly_detector.py): `ml/anomaly_detector.py`
- [Feature Extraction](https://github.com/umesh-369/skygaurd-ai/blob/main/ml/feature_extractor.py): `ml/feature_extractor.py`
- [SHAP Explanations](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/shap_service.py): `backend/explainability/shap_service.py`
- [Value Imputation](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/imputer_service.py): `backend/explainability/imputer_service.py`
- [Spatial Consensus](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/risk_engine/spatial_consensus.py): `backend/risk_engine/spatial_consensus.py`
- [Degradation Watchdog](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/explainability/degradation_service.py): `backend/explainability/degradation_service.py`

### Hazards and Response

- [Incident Lifecycle](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/incidents/incident_service.py): `backend/incidents/incident_service.py`
- [Tier 2 Hazard Risk](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/risk_engine/tier2_risk.py): `backend/risk_engine/tier2_risk.py`
- [Weather Context](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/integrations/weather/weather_service.py): `backend/integrations/weather/weather_service.py`
- [Response Recommendations](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/recommendations/recommendation_service.py): `backend/recommendations/recommendation_service.py`
- [Incident Reports](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/reports/report_service.py): `backend/reports/report_service.py`

### State and Integrations

- [MongoDB Repositories](https://github.com/umesh-369/skygaurd-ai/tree/main/backend/database/repositories): `backend/database/repositories`
- [Historical Climate Data](https://github.com/umesh-369/skygaurd-ai/blob/main/ml/data_loader.py): `ml/data_loader.py`
- [Climate Replay Adapter](https://github.com/umesh-369/skygaurd-ai/blob/main/backend/integrations/datasets/data_loader_adapter.py): `backend/integrations/datasets/data_loader_adapter.py`

### Other components

- **Operator**

## Connections

- Operator → Web App: uses
- Web App → UI State and API: loads and connects (evidence: `frontend/src/App.tsx`)
- Web App → Dashboard and Analytics: renders (evidence: `frontend/src/App.tsx`)
- Web App → Anomaly Views: renders (evidence: `frontend/src/App.tsx`)
- Web App → Fault Simulator UI: renders
- UI State and API → FastAPI Application: requests data (evidence: `frontend/src/store/useSkyGuardStore.ts`)
- FastAPI Application → Simulator Routes: mounts routers (evidence: `backend/main.py`)
- Simulator Routes → AWS Simulator Service: dispatches (evidence: `backend/api/routers/simulator.py`)
- AWS Simulator Service → Virtual Station Mesh: delegates simulation (evidence: `backend/simulator/simulator_service.py`)
- FastAPI Application → Tier 1 Detector: evaluates readings (evidence: `backend/main.py`)
- Tier 1 Detector → Isolation Forest: delegates inference (evidence: `backend/anomaly_detection/detector_service.py`)
- Isolation Forest → Feature Extraction: uses features (evidence: `ml/anomaly_detector.py`)
- FastAPI Application → Value Imputation: requests correction (evidence: `backend/main.py`)
- FastAPI Application → Incident Lifecycle: records anomalies (evidence: `backend/main.py`)
- FastAPI Application → Tier 2 Hazard Risk: calculates risk (evidence: `backend/main.py`)
- FastAPI Application → Weather Context: fetches context (evidence: `backend/main.py`)
- FastAPI Application → WebSocket Broadcast: broadcasts updates
- FastAPI Application → Communications Monitor: monitors telemetry (evidence: `backend/main.py`)
- FastAPI Application → SHAP Explanations: explains detections (evidence: `backend/main.py`)
- FastAPI Application → Spatial Consensus: checks neighbors
- FastAPI Application → Degradation Watchdog: monitors sensor health
- Incident Lifecycle → MongoDB Repositories: persists anomalies (evidence: `backend/incidents/incident_service.py`)
- FastAPI Application → Response Recommendations: creates response actions
- FastAPI Application → Incident Reports: serves reports
- Historical Climate Data → Climate Replay Adapter: supplies climate records
- UI State and API → WebSocket Broadcast: receives live events
