# kunalmamgai/hybrid-renewable-vpp architecture

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

- Interactive diagram: https://gitdiagram.com/kunalmamgai/hybrid-renewable-vpp
- Repository: https://github.com/kunalmamgai/hybrid-renewable-vpp

## Overview

SURYA is a campus-scale hybrid-renewable Virtual Power Plant: field telemetry feeds a per-building digital twin, then a recurring decision cycle forecasts conditions, protects critical loads, evaluates dispatch strategies, records decisions, and broadcasts updates. Users authenticate through the React dashboard, configure facilities, inspect live operations, and export savings reports. A separate Three.js campus simulator visualizes campus assets and scenarios. The README documents major subsystem links; only selected implementation excerpts were available, so some internal wiring is represented at the documented subsystem level.

Main entry points: [`backend/services/decision_manager.py`](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/decision_manager.py) (Decision manager), [`frontend/src/services/apiClient.ts`](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/services/apiClient.ts) (API client), [`backend/db/database.py`](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/db/database.py) (Application database), [`frontend/src/App.tsx`](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/App.tsx) (Dashboard application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["VPP backend"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Authentication routes<br/>[routes_auth.py]"]
  node_decisions_api["Decision routes"]
  node_export["Savings export<br/>[routes_export.py]"]
  node_settings["Facility settings<br/>[routes_settings.py]"]
  node_adapter["Hardware adapter<br/>[base.py]"]
  node_twin["Building digital twin"]
  node_database[("Application database<br/>[database.py]")]
  node_websocket["WebSocket manager"]
end

subgraph group_decision["Decision cycle"]
  node_scheduler["Decision scheduler<br/>[scheduler.py]"]
  node_manager["Decision manager"]
  node_forecast["Forecast engine<br/>[forecast_engine.py]"]
  node_reliability["Reliability guard"]
  node_dispatch["Dispatch optimizer"]
  node_battery["Battery scheduler"]
  node_vnm["VNM optimizer<br/>[vnm_optimizer.py]"]
  node_load_advisor["Load-shift advisor<br/>[load_advisor.py]"]
end

subgraph group_frontend["Web dashboard"]
  node_webapp["Dashboard application<br/>[App.tsx]"]
  node_auth_ui["Sign-in interface<br/>[AuthPage.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_live_data["Live data contexts<br/>[VppDataContext.tsx]"]
  node_dashboard["Operations pages<br/>[OverviewPage.tsx]"]
  node_ws_client["WebSocket client<br/>[websocketClient.ts]"]
end

subgraph group_twinview["Campus twin"]
  node_twin_app["3D campus simulator<br/>[App.jsx]"]
  node_twin_scene["Campus scene<br/>[CampusScene.jsx]"]
  node_sim_physics["Energy simulation<br/>[run_simulation.py]"]
end

node_operator(("Campus operator"))
node_field["Campus assets"]

node_operator -->|"uses"| node_webapp
node_field -->|"supplies telemetry"| node_adapter
node_api -->|"initializes"| node_adapter
node_scheduler -->|"runs cycles"| node_manager
node_manager -->|"reads sensors"| node_adapter
node_manager -->|"updates state"| node_twin
node_manager -->|"requests forecast"| node_forecast
node_manager -->|"checks constraints"| node_reliability
node_manager -->|"evaluates dispatch"| node_dispatch
node_manager -->|"evaluates battery"| node_battery
node_manager -->|"evaluates credits"| node_vnm
node_manager -->|"requests load advice"| node_load_advisor
node_twin -->|"persists state"| node_database
node_manager -->|"records decisions"| node_database
node_manager -->|"broadcasts updates"| node_websocket
node_operator -->|"signs in"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_api_client
node_api_client -->|"requests tokens"| node_auth
node_api -->|"mounts routes"| node_auth
node_webapp -->|"loads data"| node_api_client
node_api_client -->|"requests decisions"| node_decisions_api
node_api_client -->|"configures facilities"| node_settings
node_api_client -->|"requests reports"| node_export
node_decisions_api -->|"reads decisions"| node_database
node_export -->|"reads records"| node_database
node_settings -->|"reads and writes"| node_database
node_websocket -->|"pushes updates"| node_ws_client
node_ws_client -->|"updates metrics"| node_live_data
node_live_data -->|"feeds views"| node_dashboard
node_webapp -->|"routes to"| node_dashboard
node_operator -->|"explores campus"| node_twin_app
node_twin_app -->|"renders scene"| node_twin_scene
node_operator -.->|"runs simulation"| node_sim_physics

click node_api "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/main.py"
click node_auth "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_auth.py"
click node_decisions_api "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_decisions.py"
click node_export "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_export.py"
click node_settings "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_settings.py"
click node_adapter "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/adapters/base.py"
click node_twin "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/digital_twin_store.py"
click node_database "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/db/database.py"
click node_scheduler "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/scheduler.py"
click node_manager "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/decision_manager.py"
click node_forecast "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/forecast_engine.py"
click node_reliability "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/reliability_guard.py"
click node_dispatch "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/dispatch_optimizer.py"
click node_battery "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/battery_scheduler.py"
click node_vnm "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/vnm_optimizer.py"
click node_load_advisor "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/load_advisor.py"
click node_websocket "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/ws/websocket_manager.py"
click node_webapp "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/components/auth/AuthPage.tsx"
click node_api_client "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/services/apiClient.ts"
click node_live_data "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/context/VppDataContext.tsx"
click node_dashboard "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/pages/OverviewPage.tsx"
click node_ws_client "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/services/websocketClient.ts"
click node_twin_app "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/simulator/src/App.jsx"
click node_twin_scene "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/simulator/src/CampusScene.jsx"
click node_sim_physics "https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/simulator/run_simulation.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_api,node_auth,node_decisions_api,node_export,node_settings,node_adapter,node_twin,node_database,node_websocket toneBlue
class node_scheduler,node_manager,node_forecast,node_reliability,node_dispatch,node_battery,node_vnm,node_load_advisor toneAmber
class node_webapp,node_auth_ui,node_api_client,node_live_data,node_dashboard,node_ws_client toneMint
class node_twin_app,node_twin_scene,node_sim_physics toneRose
class node_operator,node_field toneIndigo
```

## Components

### VPP backend

- [FastAPI application](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_auth.py): `backend/api/routes_auth.py`
- [Decision routes](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_decisions.py): `backend/api/routes_decisions.py`
- [Savings export](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_export.py): `backend/api/routes_export.py`
- [Facility settings](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/api/routes_settings.py): `backend/api/routes_settings.py`
- [Hardware adapter](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/adapters/base.py): `backend/adapters/base.py`
- [Building digital twin](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/digital_twin_store.py): `backend/services/digital_twin_store.py`
- [Application database](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/db/database.py): `backend/db/database.py`
- [WebSocket manager](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/ws/websocket_manager.py): `backend/ws/websocket_manager.py`

### Decision cycle

- [Decision scheduler](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/scheduler.py): `backend/services/scheduler.py`
- [Decision manager](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/decision_manager.py): `backend/services/decision_manager.py`
- [Forecast engine](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/forecast_engine.py): `backend/services/forecast_engine.py`
- [Reliability guard](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/reliability_guard.py): `backend/services/reliability_guard.py`
- [Dispatch optimizer](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/dispatch_optimizer.py): `backend/services/dispatch_optimizer.py`
- [Battery scheduler](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/battery_scheduler.py): `backend/services/battery_scheduler.py`
- [VNM optimizer](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/vnm_optimizer.py): `backend/services/vnm_optimizer.py`
- [Load-shift advisor](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/services/load_advisor.py): `backend/services/load_advisor.py`

### Web dashboard

- [Dashboard application](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in interface](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/components/auth/AuthPage.tsx): `frontend/src/components/auth/AuthPage.tsx`
- [API client](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`
- [Live data contexts](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/context/VppDataContext.tsx): `frontend/src/context/VppDataContext.tsx`
- [Operations pages](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/pages/OverviewPage.tsx): `frontend/src/pages/OverviewPage.tsx`
- [WebSocket client](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/frontend/src/services/websocketClient.ts): `frontend/src/services/websocketClient.ts`

### Campus twin

- [3D campus simulator](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/simulator/src/App.jsx): `simulator/src/App.jsx`
- [Campus scene](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/simulator/src/CampusScene.jsx): `simulator/src/CampusScene.jsx`
- [Energy simulation](https://github.com/kunalmamgai/hybrid-renewable-vpp/blob/main/backend/simulator/run_simulation.py): `backend/simulator/run_simulation.py`

### Other components

- **Campus operator**
- **Campus assets**

## Connections

- Campus operator → Dashboard application: uses
- Campus assets → Hardware adapter: supplies telemetry
- FastAPI application → Hardware adapter: initializes
- Decision scheduler → Decision manager: runs cycles
- Decision manager → Hardware adapter: reads sensors
- Decision manager → Building digital twin: updates state
- Decision manager → Forecast engine: requests forecast
- Decision manager → Reliability guard: checks constraints
- Decision manager → Dispatch optimizer: evaluates dispatch
- Decision manager → Battery scheduler: evaluates battery
- Decision manager → VNM optimizer: evaluates credits
- Decision manager → Load-shift advisor: requests load advice
- Building digital twin → Application database: persists state
- Decision manager → Application database: records decisions
- Decision manager → WebSocket manager: broadcasts updates
- Campus operator → Sign-in interface: signs in
- Sign-in interface → API client: submits credentials
- API client → Authentication routes: requests tokens
- FastAPI application → Authentication routes: mounts routes
- Dashboard application → API client: loads data
- API client → Decision routes: requests decisions
- API client → Facility settings: configures facilities
- API client → Savings export: requests reports
- Decision routes → Application database: reads decisions
- Savings export → Application database: reads records
- Facility settings → Application database: reads and writes
- WebSocket manager → WebSocket client: pushes updates
- WebSocket client → Live data contexts: updates metrics
- Live data contexts → Operations pages: feeds views
- Dashboard application → Operations pages: routes to
- Campus operator → 3D campus simulator: explores campus
- 3D campus simulator → Campus scene: renders scene
- Campus operator → Energy simulation: runs simulation