# pranjalbaruah708-sudo/powerflow architecture

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

## Overview

GridFlow is a web application for distribution-network power-flow studies. Engineers import or edit a network, validate it, run a study, inspect results and recommendations, and manage saved cases and reports. The frontend also exposes equipment, scenario, and what-if tools. The backend’s study execution service converts the network model for OpenDSS, processes solver output, and produces study results. Source excerpts support the main study flow and selected frontend calls; several documented-by-code capabilities are represented without asserting unsampled internal wiring.

Main entry points: [`frontend/src/App.tsx`](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/App.tsx) (Study workspace), [`frontend/src/services/api.ts`](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/routers/study_router.py`](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/study_router.py) (Study endpoints), [`backend/app/services/study_service.py`](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/study_service.py) (Study orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Study workspace"]
  node_app["Study workspace<br/>[App.tsx]"]
  node_import_ui["Network import"]
  node_model_ui["Network editor"]
  node_whatif_ui["What-if studies"]
  node_equipment_ui["Equipment library"]
  node_results_ui["Results and diagram"]
  node_cases_ui["Cases and projects"]
  node_reports_ui["Reports export"]
  node_auth_ui["Login and session<br/>[authService.ts]"]
end

subgraph group_api["API and domain services"]
  node_api_client["API client<br/>[api.ts]"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_study_router["Study endpoints<br/>[study_router.py]"]
  node_persistence_router["Persistence endpoints"]
  node_network_model["Network schema<br/>[network_model.py]"]
  node_excel["Workbook import<br/>[excel_service.py]"]
  node_topology["Topology validation"]
  node_equipment["Equipment catalog<br/>[library_service.py]"]
  node_allocation["Load allocation"]
end

subgraph group_execution["Power-flow execution"]
  node_execution_service["Study orchestration<br/>[study_service.py]"]
  node_converter["DSS conversion<br/>[dss_converter.py]"]
  node_solver["OpenDSS solver<br/>[opendss_service.py]"]
  node_processor["Result processing"]
  node_recommendations["Recommendations"]
end

subgraph group_persistence["Identity and persistence"]
  node_auth_router["Authentication API<br/>[auth_router.py]"]
  node_storage["Study persistence<br/>[storage_service.py]"]
  node_database[("Relational database<br/>[session.py]")]
end

node_engineer(("Engineer"))

node_engineer -->|"uses"| node_app
node_app -->|"requests studies"| node_api_client
node_app -->|"opens import"| node_import_ui
node_app -->|"edits network"| node_model_ui
node_app -->|"opens simulation"| node_whatif_ui
node_app -->|"opens catalog"| node_equipment_ui
node_app -->|"manages cases"| node_cases_ui
node_app -->|"shows results"| node_results_ui
node_app -->|"exports report"| node_reports_ui
node_import_ui -->|"uploads workbook"| node_api_client
node_model_ui -->|"loads data"| node_api_client
node_whatif_ui -->|"submits changes"| node_api_client
node_equipment_ui -->|"manages equipment"| node_api_client
node_cases_ui -->|"loads cases"| node_api_client
node_api_client -->|"calls study API"| node_study_router
node_api_client -->|"calls persistence API"| node_persistence_router
node_backend -->|"registers routes"| node_study_router
node_backend -->|"registers routes"| node_persistence_router
node_backend -->|"registers routes"| node_auth_router
node_auth_ui -->|"authenticates"| node_auth_router
node_study_router -->|"validates input"| node_network_model
node_study_router -->|"parses workbook"| node_excel
node_study_router -->|"runs study"| node_execution_service
node_study_router -->|"checks topology"| node_topology
node_study_router -->|"allocates load"| node_allocation
node_study_router -->|"serves catalog"| node_equipment
node_execution_service -->|"converts network"| node_converter
node_execution_service -->|"runs power flow"| node_solver
node_execution_service -->|"processes output"| node_processor
node_execution_service -->|"generates advice"| node_recommendations
node_persistence_router -->|"reads and writes"| node_storage
node_storage -->|"persists records"| node_database
node_reports_ui -->|"uses study data"| node_api_client

click node_app "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/App.tsx"
click node_import_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/NetworkImportDialog.tsx"
click node_model_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/NetworkModelModal.tsx"
click node_whatif_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/WhatIfSimulationDialog.tsx"
click node_equipment_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/EquipmentLibraryModal.tsx"
click node_results_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/StudyResultsInspector.tsx"
click node_cases_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/StudyCasesModal.tsx"
click node_reports_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/exportStudyService.ts"
click node_api_client "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/api.ts"
click node_backend "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/main.py"
click node_study_router "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/study_router.py"
click node_persistence_router "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/persistence_router.py"
click node_network_model "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/schemas/network_model.py"
click node_excel "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/excel_service.py"
click node_topology "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/topology_validator.py"
click node_equipment "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/library_service.py"
click node_allocation "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/load_allocation_service.py"
click node_execution_service "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/study_service.py"
click node_converter "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/dss_converter.py"
click node_solver "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/opendss_service.py"
click node_processor "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/result_processor.py"
click node_recommendations "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/recommendation_engine.py"
click node_auth_ui "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/authService.ts"
click node_auth_router "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/auth_router.py"
click node_storage "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/storage_service.py"
click node_database "https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/db/session.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_import_ui,node_model_ui,node_whatif_ui,node_equipment_ui,node_results_ui,node_cases_ui,node_reports_ui,node_auth_ui toneBlue
class node_api_client,node_backend,node_study_router,node_persistence_router,node_network_model,node_excel,node_topology,node_equipment,node_allocation toneAmber
class node_execution_service,node_converter,node_solver,node_processor,node_recommendations toneMint
class node_auth_router,node_storage,node_database toneRose
class node_engineer toneIndigo
```

## Components

### Study workspace

- [Study workspace](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Network import](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/NetworkImportDialog.tsx): `frontend/src/components/NetworkImportDialog.tsx`
- [Network editor](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/NetworkModelModal.tsx): `frontend/src/components/NetworkModelModal.tsx`
- [What-if studies](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/WhatIfSimulationDialog.tsx): `frontend/src/components/WhatIfSimulationDialog.tsx`
- [Equipment library](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/EquipmentLibraryModal.tsx): `frontend/src/components/EquipmentLibraryModal.tsx`
- [Results and diagram](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/StudyResultsInspector.tsx): `frontend/src/components/StudyResultsInspector.tsx`
- [Cases and projects](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/components/StudyCasesModal.tsx): `frontend/src/components/StudyCasesModal.tsx`
- [Reports export](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/exportStudyService.ts): `frontend/src/services/exportStudyService.ts`
- [Login and session](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`

### API and domain services

- [API client](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [FastAPI application](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/main.py): `backend/app/main.py`
- [Study endpoints](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/study_router.py): `backend/app/routers/study_router.py`
- [Persistence endpoints](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/persistence_router.py): `backend/app/routers/persistence_router.py`
- [Network schema](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/schemas/network_model.py): `backend/app/schemas/network_model.py`
- [Workbook import](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/excel_service.py): `backend/app/services/excel_service.py`
- [Topology validation](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/topology_validator.py): `backend/app/services/topology_validator.py`
- [Equipment catalog](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/library_service.py): `backend/app/services/library_service.py`
- [Load allocation](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/load_allocation_service.py): `backend/app/services/load_allocation_service.py`

### Power-flow execution

- [Study orchestration](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/study_service.py): `backend/app/services/study_service.py`
- [DSS conversion](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/dss_converter.py): `backend/app/services/dss_converter.py`
- [OpenDSS solver](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/opendss_service.py): `backend/app/services/opendss_service.py`
- [Result processing](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/result_processor.py): `backend/app/services/result_processor.py`
- [Recommendations](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/recommendation_engine.py): `backend/app/services/recommendation_engine.py`

### Identity and persistence

- [Authentication API](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/routers/auth_router.py): `backend/app/routers/auth_router.py`
- [Study persistence](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [Relational database](https://github.com/pranjalbaruah708-sudo/powerflow/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Engineer**

## Connections

- Engineer → Study workspace: uses (evidence: `frontend/src/App.tsx`)
- Study workspace → API client: requests studies (evidence: `frontend/src/App.tsx`)
- Study workspace → Network import: opens import (evidence: `frontend/src/App.tsx`)
- Study workspace → Network editor: edits network (evidence: `frontend/src/App.tsx`)
- Study workspace → What-if studies: opens simulation (evidence: `frontend/src/App.tsx`)
- Study workspace → Equipment library: opens catalog (evidence: `frontend/src/App.tsx`)
- Study workspace → Cases and projects: manages cases (evidence: `frontend/src/App.tsx`)
- Study workspace → Results and diagram: shows results (evidence: `frontend/src/App.tsx`)
- Study workspace → Reports export: exports report (evidence: `frontend/src/App.tsx`)
- Network import → API client: uploads workbook (evidence: `frontend/src/components/NetworkImportDialog.tsx`)
- Network editor → API client: loads data (evidence: `frontend/src/components/NetworkModelModal.tsx`)
- What-if studies → API client: submits changes (evidence: `frontend/src/components/WhatIfSimulationDialog.tsx`)
- Equipment library → API client: manages equipment (evidence: `frontend/src/components/EquipmentLibraryModal.tsx`)
- Cases and projects → API client: loads cases (evidence: `frontend/src/components/StudyCasesModal.tsx`)
- API client → Study endpoints: calls study API (evidence: `frontend/src/services/api.ts`)
- API client → Persistence endpoints: calls persistence API (evidence: `frontend/src/services/api.ts`)
- FastAPI application → Study endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Persistence endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Authentication API: registers routes (evidence: `backend/app/main.py`)
- Login and session → Authentication API: authenticates (evidence: `frontend/src/services/authService.ts`)
- Study endpoints → Network schema: validates input (evidence: `backend/app/routers/study_router.py`)
- Study endpoints → Workbook import: parses workbook (evidence: `backend/app/routers/study_router.py`)
- Study endpoints → Study orchestration: runs study (evidence: `backend/app/routers/study_router.py`)
- Study endpoints → Topology validation: checks topology (evidence: `backend/app/main.py`)
- Study endpoints → Load allocation: allocates load (evidence: `backend/app/main.py`)
- Study endpoints → Equipment catalog: serves catalog (evidence: `backend/app/main.py`)
- Study orchestration → DSS conversion: converts network (evidence: `backend/app/services/study_service.py`)
- Study orchestration → OpenDSS solver: runs power flow (evidence: `backend/app/services/study_service.py`)
- Study orchestration → Result processing: processes output (evidence: `backend/app/services/study_service.py`)
- Study orchestration → Recommendations: generates advice (evidence: `backend/app/services/study_service.py`)
- Persistence endpoints → Study persistence: reads and writes (evidence: `backend/app/main.py`)
- Study persistence → Relational database: persists records (evidence: `backend/app/services/storage_service.py`)
- Reports export → API client: uses study data (evidence: `frontend/src/services/exportStudyService.ts`)
