# codedbydollys10/gridtwin architecture

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

## Overview

GridTwin takes solar and load CSV profiles, validates and aligns them, then simulates a distribution grid over time. Users inspect the resulting history in an interactive 3D twin and analytics, and can compare baseline and DER cases or run what-if scenarios. The README documents weather context, losses, violations, and battery behavior as product capabilities. The sampled backend excerpt is partial, so some simulation wiring follows documented responsibilities rather than inspected call sites.

Main entry points: [`backend/app/main.py`](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py) (Simulation API), [`client/src/lib/api.ts`](https://github.com/codedbydollys10/gridtwin/blob/main/client/src/lib/api.ts) (API Client), [`backend/app/simulation/timestep.py`](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/timestep.py) (Timestep Runner), [`frontend/client/src/pages/Home.tsx`](https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/pages/Home.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_home["Dashboard<br/>[Home.tsx]"]
  node_twin["3D Digital Twin<br/>[DigitalTwin.tsx]"]
  node_grid_visuals["Grid Geometry<br/>[GridBuses.tsx]"]
end

subgraph group_api["Input And API"]
  node_api_client["API Client<br/>[api.ts]"]
  node_fastapi["Simulation API<br/>[main.py]"]
  node_csv["CSV Validation<br/>[csv_service.py]"]
  node_weather["Weather Context<br/>[weather.py]"]
end

subgraph group_simulation["Simulation Engine"]
  node_network["Grid Model<br/>[network.py]"]
  node_timestep["Timestep Runner<br/>[timestep.py]"]
  node_powerflow["Power Flow<br/>[powerflow.py]"]
  node_battery["Battery Dispatch<br/>[battery.py]"]
end

subgraph group_analysis["Results And Analysis"]
  node_results["Electrical Results<br/>[results.py]"]
  node_history[("Simulation History<br/>[main.py]")]
  node_violations["Constraint Detection<br/>[violations.py]"]
  node_losses["Power Loss Analytics<br/>[main.py]"]
  node_battery_analytics["Battery Analytics<br/>[main.py]"]
  node_comparison["Baseline Comparison<br/>[comparison.py]"]
  node_whatif["What-If Analysis<br/>[whatif.py]"]
end

node_user(("Grid Operator"))
node_weather_source(("Weather Service"))

node_user -->|"operates"| node_home
node_home -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_fastapi
node_home -->|"renders grid"| node_twin
node_twin -->|"draws components"| node_grid_visuals
node_fastapi -->|"validates profiles"| node_csv
node_fastapi -->|"creates grid"| node_network
node_fastapi -->|"advances simulation"| node_timestep
node_timestep -->|"runs power flow"| node_powerflow
node_timestep -->|"dispatches storage"| node_battery
node_timestep -->|"collects outputs"| node_results
node_fastapi -->|"retains timesteps"| node_history
node_fastapi -->|"detects limits"| node_violations
node_fastapi -->|"serves loss data"| node_losses
node_fastapi -->|"serves battery data"| node_battery_analytics
node_fastapi -->|"runs comparison"| node_comparison
node_fastapi -->|"runs scenarios"| node_whatif
node_history -->|"returns history"| node_api_client
node_violations -->|"returns violations"| node_api_client
node_losses -->|"returns losses"| node_api_client
node_battery_analytics -->|"returns battery data"| node_api_client
node_comparison -->|"returns comparison"| node_api_client
node_whatif -->|"returns scenarios"| node_api_client
node_weather_source -.->|"provides weather"| node_weather
node_weather -.->|"supplies context"| node_fastapi

click node_home "https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/pages/Home.tsx"
click node_twin "https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/components/digital-twin/DigitalTwin.tsx"
click node_grid_visuals "https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/components/digital-twin/GridBuses.tsx"
click node_api_client "https://github.com/codedbydollys10/gridtwin/blob/main/client/src/lib/api.ts"
click node_fastapi "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py"
click node_csv "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/services/csv_service.py"
click node_weather "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/services/weather.py"
click node_network "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/network.py"
click node_timestep "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/timestep.py"
click node_powerflow "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/powerflow.py"
click node_battery "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/battery.py"
click node_results "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/results.py"
click node_history "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py"
click node_violations "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/violations.py"
click node_losses "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py"
click node_battery_analytics "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py"
click node_comparison "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/comparison.py"
click node_whatif "https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/whatif.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_home,node_twin,node_grid_visuals toneBlue
class node_api_client,node_fastapi,node_csv,node_weather toneAmber
class node_network,node_timestep,node_powerflow,node_battery toneMint
class node_results,node_history,node_violations,node_losses,node_battery_analytics,node_comparison,node_whatif toneRose
class node_user,node_weather_source toneIndigo
```

## Components

### User Interface

- [Dashboard](https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/pages/Home.tsx): `frontend/client/src/pages/Home.tsx`
- [3D Digital Twin](https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/components/digital-twin/DigitalTwin.tsx): `frontend/client/src/components/digital-twin/DigitalTwin.tsx`
- [Grid Geometry](https://github.com/codedbydollys10/gridtwin/blob/main/frontend/client/src/components/digital-twin/GridBuses.tsx): `frontend/client/src/components/digital-twin/GridBuses.tsx`

### Input And API

- [API Client](https://github.com/codedbydollys10/gridtwin/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`
- [Simulation API](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py): `backend/app/main.py`
- [CSV Validation](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/services/csv_service.py): `backend/app/services/csv_service.py`
- [Weather Context](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/services/weather.py): `backend/app/services/weather.py`

### Simulation Engine

- [Grid Model](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/network.py): `backend/app/simulation/network.py`
- [Timestep Runner](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/timestep.py): `backend/app/simulation/timestep.py`
- [Power Flow](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/powerflow.py): `backend/app/simulation/powerflow.py`
- [Battery Dispatch](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/battery.py): `backend/app/simulation/battery.py`

### Results And Analysis

- [Electrical Results](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/results.py): `backend/app/simulation/results.py`
- [Simulation History](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py): `backend/app/main.py`
- [Constraint Detection](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/violations.py): `backend/app/simulation/violations.py`
- [Power Loss Analytics](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py): `backend/app/main.py`
- [Battery Analytics](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/main.py): `backend/app/main.py`
- [Baseline Comparison](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/comparison.py): `backend/app/simulation/comparison.py`
- [What-If Analysis](https://github.com/codedbydollys10/gridtwin/blob/main/backend/app/simulation/whatif.py): `backend/app/simulation/whatif.py`

### Other components

- **Grid Operator**
- **Weather Service**

## Connections

- Grid Operator → Dashboard: operates
- Dashboard → API Client: requests data
- API Client → Simulation API: calls API
- Dashboard → 3D Digital Twin: renders grid
- 3D Digital Twin → Grid Geometry: draws components
- Simulation API → CSV Validation: validates profiles
- Simulation API → Grid Model: creates grid
- Simulation API → Timestep Runner: advances simulation
- Timestep Runner → Power Flow: runs power flow
- Timestep Runner → Battery Dispatch: dispatches storage
- Timestep Runner → Electrical Results: collects outputs
- Simulation API → Simulation History: retains timesteps
- Simulation API → Constraint Detection: detects limits
- Simulation API → Power Loss Analytics: serves loss data
- Simulation API → Battery Analytics: serves battery data
- Simulation API → Baseline Comparison: runs comparison
- Simulation API → What-If Analysis: runs scenarios
- Simulation History → API Client: returns history
- Constraint Detection → API Client: returns violations
- Power Loss Analytics → API Client: returns losses
- Battery Analytics → API Client: returns battery data
- Baseline Comparison → API Client: returns comparison
- What-If Analysis → API Client: returns scenarios
- Weather Service → Weather Context: provides weather
- Weather Context → Simulation API: supplies context