# aromano3141/aquagaurd architecture

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

## Overview

AquaGuard is a water-network leak detection and response dashboard. Users inspect network topology and leak results, run sandbox simulations on generated or uploaded EPANET networks, and review savings or dispatch repair teams. The main detection flow combines SCADA data and network topology with anomaly detection and leak localization, then exposes results through the API for visualization. The README documents GNN detection, sensor-based localization, simulation, and impact metrics; several related handlers are present in the tree but their implementation was not sampled, so their internal wiring is not inferred.

Main entry points: [`app/main.py`](https://github.com/aromano3141/aquagaurd/blob/main/app/main.py) (FastAPI App), [`frontend/src/App.jsx`](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/App.jsx) (Dashboard Router), [`frontend/src/api/client.js`](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/api/client.js) (API Client), [`data`](https://github.com/aromano3141/aquagaurd/tree/main/data) (Water Network Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app_ui["Dashboard Router<br/>[App.jsx]"]
  node_api_client["API Client<br/>[client.js]"]
  node_overview["Network Overview"]
  node_simulation_ui["Simulation View<br/>[Simulation.jsx]"]
  node_sandbox_ui["Sandbox View"]
  node_city_sandbox["City Sandbox<br/>[CitySandbox.jsx]"]
  node_savings_ui["Savings View<br/>[Savings.jsx]"]
  node_network_map["Network Map<br/>[NetworkMap.jsx]"]
end

subgraph group_api["API"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_pipeline_router["Pipeline API<br/>[pipeline.py]"]
  node_network_router["Network API<br/>[network.py]"]
  node_sensor_router["Sensor API<br/>[sensors.py]"]
  node_sandbox_router["Sandbox API<br/>[sandbox.py]"]
  node_savings_router["Savings API<br/>[savings.py]"]
  node_dispatch_router["Dispatch API<br/>[dispatch.py]"]
  node_report_router["Report API<br/>[report.py]"]
end

subgraph group_detection["Detection"]
  node_pipeline_service["Pipeline Service"]
  node_leak_core["Leak Detection<br/>[detect_leaks.py]"]
end

subgraph group_domain["Network Data"]
  node_data_service["SCADA Data<br/>[data_service.py]"]
  node_network_service["Network Model<br/>[network_service.py]"]
  node_water_data["Water Network Data"]
end

node_utility_user(("Utility Engineer"))
node_external_api(("HTTP API"))

node_utility_user -->|"uses"| node_app_ui
node_app_ui -->|"routes"| node_overview
node_app_ui -->|"routes"| node_simulation_ui
node_app_ui -->|"routes"| node_sandbox_ui
node_app_ui -->|"routes"| node_city_sandbox
node_app_ui -->|"routes"| node_savings_ui
node_app_ui -->|"prefetches"| node_api_client
node_sandbox_ui -->|"requests"| node_api_client
node_overview -->|"requests"| node_api_client
node_overview -->|"renders"| node_network_map
node_api_client -->|"sends requests"| node_external_api
node_external_api -->|"reaches"| node_api_app
node_api_app -->|"includes"| node_pipeline_router
node_api_app -->|"includes"| node_network_router
node_api_app -->|"includes"| node_sensor_router
node_api_app -->|"includes"| node_sandbox_router
node_api_app -->|"includes"| node_savings_router
node_api_app -->|"includes"| node_dispatch_router
node_api_app -->|"includes"| node_report_router
node_pipeline_router -->|"runs"| node_pipeline_service
node_pipeline_service -->|"executes"| node_leak_core
node_pipeline_service -->|"reads"| node_water_data
node_leak_core -->|"loads inputs"| node_water_data
node_data_service -->|"reads"| node_water_data
node_network_service -->|"loads topology"| node_water_data
node_network_router -->|"serves topology"| node_network_service

click node_app_ui "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/api/client.js"
click node_overview "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/NetworkOverview.jsx"
click node_simulation_ui "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/Simulation.jsx"
click node_sandbox_ui "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/SandboxProcedural.jsx"
click node_city_sandbox "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/CitySandbox.jsx"
click node_savings_ui "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/Savings.jsx"
click node_network_map "https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/components/NetworkMap.jsx"
click node_api_app "https://github.com/aromano3141/aquagaurd/blob/main/app/main.py"
click node_pipeline_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/pipeline.py"
click node_network_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/network.py"
click node_sensor_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/sensors.py"
click node_sandbox_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/sandbox.py"
click node_savings_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/savings.py"
click node_dispatch_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/dispatch.py"
click node_report_router "https://github.com/aromano3141/aquagaurd/blob/main/app/routers/report.py"
click node_pipeline_service "https://github.com/aromano3141/aquagaurd/blob/main/app/services/pipeline_service.py"
click node_leak_core "https://github.com/aromano3141/aquagaurd/blob/main/app/core/detect_leaks.py"
click node_data_service "https://github.com/aromano3141/aquagaurd/blob/main/app/services/data_service.py"
click node_network_service "https://github.com/aromano3141/aquagaurd/blob/main/app/services/network_service.py"
click node_water_data "https://github.com/aromano3141/aquagaurd/tree/main/data"

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_ui,node_api_client,node_overview,node_simulation_ui,node_sandbox_ui,node_city_sandbox,node_savings_ui,node_network_map toneBlue
class node_api_app,node_pipeline_router,node_network_router,node_sensor_router,node_sandbox_router,node_savings_router,node_dispatch_router,node_report_router toneAmber
class node_pipeline_service,node_leak_core,node_external_api toneMint
class node_data_service,node_network_service,node_water_data toneRose
class node_utility_user toneIndigo
```

## Components

### Dashboard

- [Dashboard Router](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API Client](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Network Overview](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/NetworkOverview.jsx): `frontend/src/pages/NetworkOverview.jsx`
- [Simulation View](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/Simulation.jsx): `frontend/src/pages/Simulation.jsx`
- [Sandbox View](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/SandboxProcedural.jsx): `frontend/src/pages/SandboxProcedural.jsx`
- [City Sandbox](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/CitySandbox.jsx): `frontend/src/pages/CitySandbox.jsx`
- [Savings View](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/pages/Savings.jsx): `frontend/src/pages/Savings.jsx`
- [Network Map](https://github.com/aromano3141/aquagaurd/blob/main/frontend/src/components/NetworkMap.jsx): `frontend/src/components/NetworkMap.jsx`

### API

- [FastAPI App](https://github.com/aromano3141/aquagaurd/blob/main/app/main.py): `app/main.py`
- [Pipeline API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/pipeline.py): `app/routers/pipeline.py`
- [Network API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/network.py): `app/routers/network.py`
- [Sensor API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/sensors.py): `app/routers/sensors.py`
- [Sandbox API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/sandbox.py): `app/routers/sandbox.py`
- [Savings API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/savings.py): `app/routers/savings.py`
- [Dispatch API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/dispatch.py): `app/routers/dispatch.py`
- [Report API](https://github.com/aromano3141/aquagaurd/blob/main/app/routers/report.py): `app/routers/report.py`

### Detection

- [Pipeline Service](https://github.com/aromano3141/aquagaurd/blob/main/app/services/pipeline_service.py): `app/services/pipeline_service.py`
- [Leak Detection](https://github.com/aromano3141/aquagaurd/blob/main/app/core/detect_leaks.py): `app/core/detect_leaks.py`

### Network Data

- [SCADA Data](https://github.com/aromano3141/aquagaurd/blob/main/app/services/data_service.py): `app/services/data_service.py`
- [Network Model](https://github.com/aromano3141/aquagaurd/blob/main/app/services/network_service.py): `app/services/network_service.py`
- [Water Network Data](https://github.com/aromano3141/aquagaurd/tree/main/data): `data`

### Other components

- **Utility Engineer**
- **HTTP API**

## Connections

- Utility Engineer → Dashboard Router: uses
- Dashboard Router → Network Overview: routes
- Dashboard Router → Simulation View: routes
- Dashboard Router → Sandbox View: routes
- Dashboard Router → City Sandbox: routes
- Dashboard Router → Savings View: routes
- Dashboard Router → API Client: prefetches
- Sandbox View → API Client: requests
- Network Overview → API Client: requests
- Network Overview → Network Map: renders
- API Client → HTTP API: sends requests
- HTTP API → FastAPI App: reaches
- FastAPI App → Pipeline API: includes
- FastAPI App → Network API: includes
- FastAPI App → Sensor API: includes
- FastAPI App → Sandbox API: includes
- FastAPI App → Savings API: includes
- FastAPI App → Dispatch API: includes
- FastAPI App → Report API: includes
- Pipeline API → Pipeline Service: runs
- Pipeline Service → Leak Detection: executes
- Pipeline Service → Water Network Data: reads
- Leak Detection → Water Network Data: loads inputs
- SCADA Data → Water Network Data: reads
- Network Model → Water Network Data: loads topology
- Network API → Network Model: serves topology