# kulalpavan/skyguard-ai-mini-project architecture

> Architecture diagram of the GitHub repository kulalpavan/skyguard-ai-mini-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kulalpavan/skyguard-ai-mini-project
- Repository: https://github.com/kulalpavan/skyguard-ai-mini-project

## Overview

SkyGuard-AI is a weather-station anomaly detection and fleet operations product. Station telemetry is ingested and assessed against station-specific baselines, physical/QC checks, and fleet evidence; the system then explains classifications, supports recovery, and exposes monitoring, incident, maintenance, and model-governance workflows. The graph includes the documented analytics stages and the sampled backend, ML, and frontend layers. Some API and operational subsystem internals were not sampled, so their links are limited to documented or indexed relationships.

Main entry points: [`backend/app/services/observation_pipeline.py`](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/observation_pipeline.py) (Observation Assessment), [`src/utils/apiClient.js`](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/utils/apiClient.js) (Backend API Client), [`backend/app/services/training_service.py`](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/training_service.py) (Model Training), [`src/context/WeatherContext.jsx`](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/context/WeatherContext.jsx) (Fleet State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Station Edge"]
  node_station_device(("Weather Station"))
  node_esp32["ESP32 Edge<br/>[skyguard_edge.h]"]
end

subgraph group_backend["Backend Services"]
  node_telemetry_api["Telemetry API<br/>[telemetry.py]"]
  node_observation_pipeline["Observation Assessment"]
  node_database[("Operational Database<br/>[database.py]")]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_security["Auth Security<br/>[security.py]"]
  node_stations_api["Station API<br/>[stations.py]"]
  node_incidents_api["Incident API<br/>[incidents.py]"]
  node_maintenance_api["Maintenance API<br/>[maintenance.py]"]
  node_evidence_api["Evidence API<br/>[evidence.py]"]
  node_model_store[("Model Artifacts<br/>[model_storage.py]")]
end

subgraph group_analytics["Assessment Intelligence"]
  node_climatology["Station Climatology"]
  node_feature_engine["Residual Features<br/>[feature_engine.py]"]
  node_thermo["Thermodynamic Checks<br/>[thermo_engine.py]"]
  node_station_ml["Adaptive Anomaly ML"]
  node_spatial["Fleet Adjudication<br/>[spatial_engine.py]"]
  node_imputation["Value Reconstruction"]
  node_health["Sensor Health<br/>[sensor_health.py]"]
  node_root_cause["Root Cause Reasoning"]
  node_training["Model Training"]
end

subgraph group_operator["Operator Console"]
  node_auth_context["Session and Station Access<br/>[AuthContext.jsx]"]
  node_api_client["Backend API Client<br/>[apiClient.js]"]
  node_weather_context["Fleet State<br/>[WeatherContext.jsx]"]
  node_web_app["Console View Router<br/>[App.jsx]"]
  node_station_views["Station Operations Views<br/>[StationHUD.jsx]"]
  node_fleet_views["Fleet and Incident Views<br/>[Incidents.jsx]"]
  node_model_views["Model Governance Views"]
  node_audio["Operator Audio Alerts<br/>[audio.js]"]
end

node_web_user(("Operator"))

node_station_device -.->|"sends readings"| node_esp32
node_esp32 -.->|"uploads telemetry"| node_telemetry_api
node_telemetry_api -.->|"assesses observations"| node_observation_pipeline
node_observation_pipeline -->|"reads and writes"| node_database
node_observation_pipeline -.->|"checks baseline"| node_climatology
node_observation_pipeline -->|"checks physics"| node_thermo
node_observation_pipeline -->|"builds features"| node_feature_engine
node_feature_engine -->|"computes residuals"| node_climatology
node_feature_engine -->|"derives features"| node_thermo
node_observation_pipeline -.->|"scores station"| node_station_ml
node_observation_pipeline -->|"adjudicates peers"| node_spatial
node_observation_pipeline -->|"checks sensor health"| node_health
node_observation_pipeline -->|"requests reasoning"| node_root_cause
node_observation_pipeline -.->|"reconstructs values"| node_imputation
node_observation_pipeline -->|"requests training"| node_training
node_training -->|"builds training features"| node_feature_engine
node_training -->|"fits baseline"| node_climatology
node_training -->|"trains station model"| node_station_ml
node_training -->|"persists artifacts"| node_model_store
node_model_store -.->|"uses configured storage"| node_database
node_auth_api -->|"verifies credentials"| node_security
node_auth_api -->|"reads accounts"| node_database
node_web_user -.->|"uses console"| node_web_app
node_web_app -->|"checks session"| node_auth_context
node_web_app -->|"selects views"| node_weather_context
node_auth_context -->|"authenticates and loads stations"| node_api_client
node_weather_context -->|"fetches fleet data"| node_api_client
node_weather_context -->|"runs fleet analysis"| node_spatial
node_weather_context -->|"plays alerts"| node_audio
node_station_views -->|"requests station data"| node_api_client
node_fleet_views -.->|"shows incidents"| node_weather_context
node_model_views -.->|"manages model state"| node_api_client
node_api_client -->|"posts telemetry"| node_telemetry_api
node_api_client -->|"requests station data"| node_stations_api
node_api_client -->|"requests incidents"| node_incidents_api
node_api_client -.->|"requests evidence"| node_evidence_api
node_api_client -.->|"requests maintenance"| node_maintenance_api

click node_esp32 "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ESP32/skyguard_edge.h"
click node_telemetry_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/telemetry.py"
click node_observation_pipeline "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/observation_pipeline.py"
click node_database "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/storage/database.py"
click node_auth_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/auth.py"
click node_security "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/auth/security.py"
click node_stations_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/stations.py"
click node_incidents_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/incidents.py"
click node_maintenance_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/maintenance.py"
click node_evidence_api "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/evidence.py"
click node_climatology "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/climatology_engine.py"
click node_feature_engine "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/feature_engine.py"
click node_thermo "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/thermo_engine.py"
click node_station_ml "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/station_adaptive_pipeline.py"
click node_spatial "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/spatial_engine.py"
click node_imputation "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/imputation_engine.py"
click node_health "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/sensor_health.py"
click node_root_cause "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/incident_reasoning.py"
click node_training "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/training_service.py"
click node_model_store "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/model_storage.py"
click node_auth_context "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/context/AuthContext.jsx"
click node_api_client "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/utils/apiClient.js"
click node_weather_context "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/context/WeatherContext.jsx"
click node_web_app "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/App.jsx"
click node_station_views "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/StationHUD.jsx"
click node_fleet_views "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/Incidents.jsx"
click node_model_views "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/ModelGovernance.jsx"
click node_audio "https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/utils/audio.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_station_device,node_esp32 toneBlue
class node_telemetry_api,node_observation_pipeline,node_database,node_auth_api,node_security,node_stations_api,node_incidents_api,node_maintenance_api,node_evidence_api,node_model_store toneAmber
class node_climatology,node_feature_engine,node_thermo,node_station_ml,node_spatial,node_imputation,node_health,node_root_cause,node_training toneMint
class node_auth_context,node_api_client,node_weather_context,node_web_app,node_station_views,node_fleet_views,node_model_views,node_audio toneRose
class node_web_user toneIndigo
```

## Components

### Station Edge

- **Weather Station**
- [ESP32 Edge](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ESP32/skyguard_edge.h): `ESP32/skyguard_edge.h`

### Backend Services

- [Telemetry API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/telemetry.py): `backend/app/api/v1/telemetry.py`
- [Observation Assessment](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/observation_pipeline.py): `backend/app/services/observation_pipeline.py`
- [Operational Database](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/storage/database.py): `backend/app/storage/database.py`
- [Authentication API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Auth Security](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/auth/security.py): `backend/app/auth/security.py`
- [Station API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/stations.py): `backend/app/api/v1/stations.py`
- [Incident API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/incidents.py): `backend/app/api/v1/incidents.py`
- [Maintenance API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/maintenance.py): `backend/app/api/v1/maintenance.py`
- [Evidence API](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/api/v1/evidence.py): `backend/app/api/v1/evidence.py`
- [Model Artifacts](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/model_storage.py): `backend/app/services/model_storage.py`

### Assessment Intelligence

- [Station Climatology](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/climatology_engine.py): `ml/climatology_engine.py`
- [Residual Features](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/feature_engine.py): `ml/feature_engine.py`
- [Thermodynamic Checks](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/thermo_engine.py): `ml/thermo_engine.py`
- [Adaptive Anomaly ML](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/station_adaptive_pipeline.py): `ml/station_adaptive_pipeline.py`
- [Fleet Adjudication](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/spatial_engine.py): `ml/spatial_engine.py`
- [Value Reconstruction](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/imputation_engine.py): `ml/imputation_engine.py`
- [Sensor Health](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/ml/sensor_health.py): `ml/sensor_health.py`
- [Root Cause Reasoning](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/incident_reasoning.py): `backend/app/services/incident_reasoning.py`
- [Model Training](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/backend/app/services/training_service.py): `backend/app/services/training_service.py`

### Operator Console

- [Session and Station Access](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Backend API Client](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/utils/apiClient.js): `src/utils/apiClient.js`
- [Fleet State](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/context/WeatherContext.jsx): `src/context/WeatherContext.jsx`
- [Console View Router](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/App.jsx): `src/App.jsx`
- [Station Operations Views](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/StationHUD.jsx): `src/components/views/StationHUD.jsx`
- [Fleet and Incident Views](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/Incidents.jsx): `src/components/views/Incidents.jsx`
- [Model Governance Views](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/components/views/ModelGovernance.jsx): `src/components/views/ModelGovernance.jsx`
- [Operator Audio Alerts](https://github.com/kulalpavan/skyguard-ai-mini-project/blob/main/src/utils/audio.js): `src/utils/audio.js`

### Other components

- **Operator**

## Connections

- Weather Station → ESP32 Edge: sends readings
- ESP32 Edge → Telemetry API: uploads telemetry
- Telemetry API → Observation Assessment: assesses observations
- Observation Assessment → Operational Database: reads and writes (evidence: `backend/app/services/observation_pipeline.py`)
- Observation Assessment → Station Climatology: checks baseline
- Observation Assessment → Thermodynamic Checks: checks physics (evidence: `backend/app/services/observation_pipeline.py`)
- Observation Assessment → Residual Features: builds features (evidence: `backend/app/services/observation_pipeline.py`)
- Residual Features → Station Climatology: computes residuals (evidence: `ml/feature_engine.py`)
- Residual Features → Thermodynamic Checks: derives features (evidence: `ml/feature_engine.py`)
- Observation Assessment → Adaptive Anomaly ML: scores station
- Observation Assessment → Fleet Adjudication: adjudicates peers (evidence: `backend/app/services/observation_pipeline.py`)
- Observation Assessment → Sensor Health: checks sensor health (evidence: `backend/app/services/observation_pipeline.py`)
- Observation Assessment → Root Cause Reasoning: requests reasoning (evidence: `backend/app/services/observation_pipeline.py`)
- Observation Assessment → Value Reconstruction: reconstructs values
- Observation Assessment → Model Training: requests training (evidence: `backend/app/services/observation_pipeline.py`)
- Model Training → Residual Features: builds training features (evidence: `backend/app/services/training_service.py`)
- Model Training → Station Climatology: fits baseline (evidence: `backend/app/services/training_service.py`)
- Model Training → Adaptive Anomaly ML: trains station model (evidence: `backend/app/services/training_service.py`)
- Model Training → Model Artifacts: persists artifacts (evidence: `backend/app/services/training_service.py`)
- Model Artifacts → Operational Database: uses configured storage
- Authentication API → Auth Security: verifies credentials (evidence: `backend/app/api/v1/auth.py`)
- Authentication API → Operational Database: reads accounts (evidence: `backend/app/api/v1/auth.py`)
- Operator → Console View Router: uses console
- Console View Router → Session and Station Access: checks session (evidence: `src/App.jsx`)
- Console View Router → Fleet State: selects views (evidence: `src/App.jsx`)
- Session and Station Access → Backend API Client: authenticates and loads stations (evidence: `src/context/AuthContext.jsx`)
- Fleet State → Backend API Client: fetches fleet data (evidence: `src/context/WeatherContext.jsx`)
- Fleet State → Fleet Adjudication: runs fleet analysis (evidence: `src/context/WeatherContext.jsx`)
- Fleet State → Operator Audio Alerts: plays alerts (evidence: `src/context/WeatherContext.jsx`)
- Station Operations Views → Backend API Client: requests station data (evidence: `src/components/views/StationHUD.jsx`)
- Fleet and Incident Views → Fleet State: shows incidents
- Model Governance Views → Backend API Client: manages model state
- Backend API Client → Telemetry API: posts telemetry (evidence: `src/utils/apiClient.js`)
- Backend API Client → Station API: requests station data (evidence: `src/utils/apiClient.js`)
- Backend API Client → Incident API: requests incidents (evidence: `src/utils/apiClient.js`)
- Backend API Client → Evidence API: requests evidence
- Backend API Client → Maintenance API: requests maintenance
