# soumadipdutta/sparkles architecture

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

- Interactive diagram: https://gitdiagram.com/soumadipdutta/sparkles
- Repository: https://github.com/soumadipdutta/sparkles

## Overview

Sparkles is a smart-water monitoring portal with statewide and plant-level monitoring, analytics and reports, and critical-alert/incident-response views. The main user workflow is to open a monitoring view, inspect water-quality and operational status, then review trends or obtain a report; alert handling is a separate capability. The tree also contains a standalone FastAPI service for health-risk checks, SMS awareness, and PDF reports. The README provides no further architecture detail, and several integrated routes and frontend API calls were not sampled, so those internal links are omitted.

Main entry points: [`Backend/main.py`](https://github.com/soumadipdutta/sparkles/blob/main/Backend/main.py) (Standalone API App), [`SIH/integrated_frontend/src/App.jsx`](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/App.jsx) (Portal Router), [`SIH/integrated_backend/website/main.py`](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/main.py) (Integrated API App), [`Backend/services/sms_service.py`](https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/sms_service.py) (SMS Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integrated_ui["Monitoring Portal"]
  node_portal["Portal Router<br/>[App.jsx]"]
  node_overview["Statewide Overview"]
  node_telemetry["Plant Telemetry<br/>[PlantTelemetry.jsx]"]
  node_analytics["Reports Analytics"]
  node_alerts["Critical Alerts<br/>[CriticalAlerts.jsx]"]
  node_frontend_api["Frontend API Client<br/>[api.js]"]
end

subgraph group_integrated_api["Integrated API"]
  node_integrated_main["Integrated API App<br/>[main.py]"]
  node_dashboard_routes["Dashboard Routes<br/>[dashboard.py]"]
  node_settings_routes["Settings Routes<br/>[settings.py]"]
  node_reports_routes["Reports Routes<br/>[reports.py]"]
  node_dashboard_service["Dashboard Service<br/>[dashboard.py]"]
  node_settings_service["Settings Service<br/>[settings.py]"]
  node_telemetry_processor["Telemetry Processor"]
  node_report_service_integrated["Report Data Service<br/>[report_service.py]"]
  node_firebase["Firebase Access<br/>[firebase.py]"]
end

subgraph group_standalone["Standalone API"]
  node_standalone_main["Standalone API App<br/>[main.py]"]
  node_risk["Health Risk Check<br/>[health_risks.py]"]
  node_sms["SMS Service<br/>[sms_service.py]"]
end

subgraph group_reporting["Report Generation"]
  node_report_service["Report Data Service<br/>[report_service.py]"]
  node_pdf_service["PDF Report Builder"]
end

node_operator(("Portal User"))
node_sms_provider["SMS Provider"]

node_operator -->|"uses"| node_portal
node_portal -->|"routes to"| node_overview
node_portal -->|"routes to"| node_telemetry
node_portal -->|"routes to"| node_analytics
node_portal -->|"routes to"| node_alerts
node_integrated_main -->|"registers"| node_dashboard_routes
node_integrated_main -->|"registers"| node_settings_routes
node_integrated_main -->|"registers"| node_reports_routes
node_report_service_integrated -->|"reads device data"| node_firebase
node_standalone_main -->|"calls"| node_risk
node_standalone_main -->|"calls"| node_sms
node_standalone_main -->|"calls"| node_report_service
node_standalone_main -->|"generates PDF"| node_pdf_service
node_standalone_main -->|"checks risk"| node_risk
node_standalone_main -->|"loads report data"| node_report_service
node_sms -.->|"sends message"| node_sms_provider

click node_portal "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/App.jsx"
click node_overview "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/StatewideOverview.jsx"
click node_telemetry "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/PlantTelemetry.jsx"
click node_analytics "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/ReportsAndAnalytics.jsx"
click node_alerts "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/CriticalAlerts.jsx"
click node_frontend_api "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/services/api.js"
click node_integrated_main "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/main.py"
click node_dashboard_routes "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/dashboard.py"
click node_settings_routes "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/settings.py"
click node_reports_routes "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/reports.py"
click node_dashboard_service "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/dashboard.py"
click node_settings_service "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/settings.py"
click node_telemetry_processor "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/telemetry_processor.py"
click node_report_service_integrated "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/report_service.py"
click node_firebase "https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/firebase.py"
click node_standalone_main "https://github.com/soumadipdutta/sparkles/blob/main/Backend/main.py"
click node_risk "https://github.com/soumadipdutta/sparkles/blob/main/Backend/risk_services/health_risks.py"
click node_sms "https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/sms_service.py"
click node_report_service "https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/report_service.py"
click node_pdf_service "https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/report_download_service.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_portal,node_overview,node_telemetry,node_analytics,node_alerts,node_frontend_api,node_operator toneBlue
class node_integrated_main,node_dashboard_routes,node_settings_routes,node_reports_routes,node_dashboard_service,node_settings_service,node_telemetry_processor,node_report_service_integrated,node_firebase toneAmber
class node_standalone_main,node_risk,node_sms toneMint
class node_report_service,node_pdf_service toneRose
class node_sms_provider toneIndigo
```

## Components

### Monitoring Portal

- [Portal Router](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/App.jsx): `SIH/integrated_frontend/src/App.jsx`
- [Statewide Overview](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/StatewideOverview.jsx): `SIH/integrated_frontend/src/pages/StatewideOverview.jsx`
- [Plant Telemetry](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/PlantTelemetry.jsx): `SIH/integrated_frontend/src/pages/PlantTelemetry.jsx`
- [Reports Analytics](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/ReportsAndAnalytics.jsx): `SIH/integrated_frontend/src/pages/ReportsAndAnalytics.jsx`
- [Critical Alerts](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/pages/CriticalAlerts.jsx): `SIH/integrated_frontend/src/pages/CriticalAlerts.jsx`
- [Frontend API Client](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_frontend/src/services/api.js): `SIH/integrated_frontend/src/services/api.js`

### Integrated API

- [Integrated API App](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/main.py): `SIH/integrated_backend/website/main.py`
- [Dashboard Routes](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/dashboard.py): `SIH/integrated_backend/website/routes/dashboard.py`
- [Settings Routes](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/settings.py): `SIH/integrated_backend/website/routes/settings.py`
- [Reports Routes](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/routes/reports.py): `SIH/integrated_backend/website/routes/reports.py`
- [Dashboard Service](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/dashboard.py): `SIH/integrated_backend/website/services/dashboard.py`
- [Settings Service](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/settings.py): `SIH/integrated_backend/website/services/settings.py`
- [Telemetry Processor](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/telemetry_processor.py): `SIH/integrated_backend/website/services/telemetry_processor.py`
- [Report Data Service](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/report_service.py): `SIH/integrated_backend/website/services/report_service.py`
- [Firebase Access](https://github.com/soumadipdutta/sparkles/blob/main/SIH/integrated_backend/website/services/firebase.py): `SIH/integrated_backend/website/services/firebase.py`

### Standalone API

- [Standalone API App](https://github.com/soumadipdutta/sparkles/blob/main/Backend/main.py): `Backend/main.py`
- [Health Risk Check](https://github.com/soumadipdutta/sparkles/blob/main/Backend/risk_services/health_risks.py): `Backend/risk_services/health_risks.py`
- [SMS Service](https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/sms_service.py): `Backend/services/sms_service.py`

### Report Generation

- [Report Data Service](https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/report_service.py): `Backend/services/report_service.py`
- [PDF Report Builder](https://github.com/soumadipdutta/sparkles/blob/main/Backend/services/report_download_service.py): `Backend/services/report_download_service.py`

### Other components

- **Portal User**
- **SMS Provider**

## Connections

- Portal User → Portal Router: uses
- Portal Router → Statewide Overview: routes to
- Portal Router → Plant Telemetry: routes to
- Portal Router → Reports Analytics: routes to
- Portal Router → Critical Alerts: routes to
- Integrated API App → Dashboard Routes: registers
- Integrated API App → Settings Routes: registers
- Integrated API App → Reports Routes: registers
- Report Data Service → Firebase Access: reads device data
- Standalone API App → Health Risk Check: calls
- Standalone API App → SMS Service: calls
- Standalone API App → Report Data Service: calls
- Standalone API App → PDF Report Builder: generates PDF
- Standalone API App → Health Risk Check: checks risk
- Standalone API App → Report Data Service: loads report data
- SMS Service → SMS Provider: sends message