# ryle-kun/water-system-connected architecture

> Architecture diagram of the GitHub repository ryle-kun/water-system-connected, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryle-kun/water-system-connected
- Repository: https://github.com/ryle-kun/water-system-connected

## Overview

Barangay Water System is an offline-capable IoT monitoring and control app for a three-tank water system, with optional cloud access. The main workflow runs from Arduino sensor readings through the serial bridge and FastAPI API into stored readings and dashboard updates; users can also authenticate, review alerts and schedules, and issue valve commands. The graph preserves those documented capabilities, but several service implementations and the serial/WebSocket internals were not sampled, so uncertain links are left dashed or omitted.

Main entry points: [`backend/main.py`](https://github.com/ryle-kun/water-system-connected/blob/main/backend/main.py) (FastAPI API), [`backend/models.py`](https://github.com/ryle-kun/water-system-connected/blob/main/backend/models.py) (Domain Models), [`frontend/src/pages/Dashboard.jsx`](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/pages/Dashboard.jsx) (Web Dashboard), [`frontend/src/App.jsx`](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/App.jsx) (Web App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Sensor Ingestion"]
  node_serial["Serial Bridge<br/>[serial_bridge.py]"]
end

subgraph group_backend["API and Services"]
  node_api["FastAPI API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_sensors["Sensor Service<br/>[sensor_service.py]"]
  node_valves["Valve Service<br/>[valve_service.py]"]
  node_alerts["Alert Service<br/>[alert_service.py]"]
  node_schedules["Schedule Service"]
  node_schemas["API Schemas<br/>[schemas.py]"]
end

subgraph group_state["Data and Realtime"]
  node_database["Database Session<br/>[database.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_websocket["WebSocket Manager"]
end

subgraph group_clients["User Interfaces"]
  node_web["Web Dashboard<br/>[Dashboard.jsx]"]
  node_webapp["Web App Shell<br/>[App.jsx]"]
  node_websocket_hook["WebSocket Hook<br/>[useWebSocket.js]"]
  node_mobile["Mobile Dashboard<br/>[DashboardScreen.js]"]
  node_mobileapp["Mobile App Shell<br/>[App.js]"]
  node_frontend_login["Web Login<br/>[LoginPage.jsx]"]
end

node_arduino["Arduino"]
node_operator(("Operator or Official"))
node_cloud["Cloud VPS"]

node_arduino -->|"sends readings"| node_serial
node_serial -.->|"posts readings"| node_api
node_operator -->|"uses"| node_webapp
node_webapp -->|"renders"| node_web
node_webapp -->|"renders"| node_frontend_login
node_operator -.->|"uses"| node_mobileapp
node_mobileapp -->|"renders"| node_mobile
node_api -->|"delegates to"| node_sensors
node_api -->|"delegates to"| node_schedules
node_api -.->|"opens sessions"| node_database
node_api -.->|"validates with"| node_schemas
node_api -.->|"authenticates via"| node_auth
node_api -.->|"dispatches commands"| node_valves
node_api -.->|"serves alerts"| node_alerts
node_sensors -->|"reads and writes"| node_models
node_schedules -->|"reads and writes"| node_models
node_valves -.->|"records commands"| node_models
node_alerts -.->|"reads alerts"| node_models
node_api -.->|"broadcasts updates"| node_websocket
node_web -.->|"uses updates"| node_websocket_hook
node_websocket_hook -.->|"connects to"| node_websocket
node_web -.->|"requests dashboard"| node_api
node_mobile -.->|"requests data"| node_api
node_cloud -.->|"remote access"| node_api

click node_serial "https://github.com/ryle-kun/water-system-connected/blob/main/backend/serial_bridge.py"
click node_api "https://github.com/ryle-kun/water-system-connected/blob/main/backend/main.py"
click node_auth "https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/auth_service.py"
click node_sensors "https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/sensor_service.py"
click node_valves "https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/valve_service.py"
click node_alerts "https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/alert_service.py"
click node_schedules "https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/schedule_service.py"
click node_schemas "https://github.com/ryle-kun/water-system-connected/blob/main/backend/schemas.py"
click node_database "https://github.com/ryle-kun/water-system-connected/blob/main/backend/database.py"
click node_models "https://github.com/ryle-kun/water-system-connected/blob/main/backend/models.py"
click node_websocket "https://github.com/ryle-kun/water-system-connected/blob/main/backend/websocket_manager.py"
click node_web "https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/pages/Dashboard.jsx"
click node_webapp "https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/App.jsx"
click node_websocket_hook "https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/hooks/useWebSocket.js"
click node_mobile "https://github.com/ryle-kun/water-system-connected/blob/main/frontend-mobile/src/screens/DashboardScreen.js"
click node_mobileapp "https://github.com/ryle-kun/water-system-connected/blob/main/frontend-mobile/App.js"
click node_frontend_login "https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/pages/LoginPage.jsx"

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_serial toneBlue
class node_api,node_auth,node_sensors,node_valves,node_alerts,node_schedules,node_schemas toneAmber
class node_database,node_models,node_websocket toneMint
class node_web,node_webapp,node_websocket_hook,node_mobile,node_mobileapp,node_frontend_login toneRose
class node_arduino,node_operator,node_cloud toneIndigo
```

## Components

### Sensor Ingestion

- [Serial Bridge](https://github.com/ryle-kun/water-system-connected/blob/main/backend/serial_bridge.py): `backend/serial_bridge.py`

### API and Services

- [FastAPI API](https://github.com/ryle-kun/water-system-connected/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Sensor Service](https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/sensor_service.py): `backend/services/sensor_service.py`
- [Valve Service](https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/valve_service.py): `backend/services/valve_service.py`
- [Alert Service](https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/alert_service.py): `backend/services/alert_service.py`
- [Schedule Service](https://github.com/ryle-kun/water-system-connected/blob/main/backend/services/schedule_service.py): `backend/services/schedule_service.py`
- [API Schemas](https://github.com/ryle-kun/water-system-connected/blob/main/backend/schemas.py): `backend/schemas.py`

### Data and Realtime

- [Database Session](https://github.com/ryle-kun/water-system-connected/blob/main/backend/database.py): `backend/database.py`
- [Domain Models](https://github.com/ryle-kun/water-system-connected/blob/main/backend/models.py): `backend/models.py`
- [WebSocket Manager](https://github.com/ryle-kun/water-system-connected/blob/main/backend/websocket_manager.py): `backend/websocket_manager.py`

### User Interfaces

- [Web Dashboard](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Web App Shell](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [WebSocket Hook](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/hooks/useWebSocket.js): `frontend/src/hooks/useWebSocket.js`
- [Mobile Dashboard](https://github.com/ryle-kun/water-system-connected/blob/main/frontend-mobile/src/screens/DashboardScreen.js): `frontend-mobile/src/screens/DashboardScreen.js`
- [Mobile App Shell](https://github.com/ryle-kun/water-system-connected/blob/main/frontend-mobile/App.js): `frontend-mobile/App.js`
- [Web Login](https://github.com/ryle-kun/water-system-connected/blob/main/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`

### Other components

- **Arduino**
- **Operator or Official**
- **Cloud VPS**

## Connections

- Arduino → Serial Bridge: sends readings (evidence: `README.md`)
- Serial Bridge → FastAPI API: posts readings (evidence: `backend/main.py`)
- Operator or Official → Web App Shell: uses (evidence: `README.md`)
- Web App Shell → Web Dashboard: renders (evidence: `frontend/src/App.jsx`)
- Web App Shell → Web Login: renders (evidence: `frontend/src/App.jsx`)
- Operator or Official → Mobile App Shell: uses
- Mobile App Shell → Mobile Dashboard: renders (evidence: `frontend-mobile/App.js`)
- FastAPI API → Sensor Service: delegates to (evidence: `backend/main.py`)
- FastAPI API → Schedule Service: delegates to (evidence: `backend/main.py`)
- FastAPI API → Database Session: opens sessions (evidence: `backend/main.py`)
- FastAPI API → API Schemas: validates with (evidence: `backend/main.py`)
- FastAPI API → Authentication: authenticates via
- FastAPI API → Valve Service: dispatches commands
- FastAPI API → Alert Service: serves alerts
- Sensor Service → Domain Models: reads and writes (evidence: `backend/services/sensor_service.py`)
- Schedule Service → Domain Models: reads and writes (evidence: `backend/services/schedule_service.py`)
- Valve Service → Domain Models: records commands
- Alert Service → Domain Models: reads alerts
- FastAPI API → WebSocket Manager: broadcasts updates (evidence: `backend/main.py`)
- Web Dashboard → WebSocket Hook: uses updates
- WebSocket Hook → WebSocket Manager: connects to
- Web Dashboard → FastAPI API: requests dashboard
- Mobile Dashboard → FastAPI API: requests data
- Cloud VPS → FastAPI API: remote access (evidence: `README.md`)