# ryle-kun/project-water-filter-system-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/ryle-kun/project-water-filter-system-v2
- Repository: https://github.com/ryle-kun/project-water-filter-system-v2

## Overview

This is an IoT water-monitoring and distribution-control system: controller readings enter the backend, are persisted and exposed through APIs, and operators use a web dashboard to inspect status, alerts, history, schedules, and valves. The README documents serial hardware communication and real-time WebSocket updates, but cautions that physical integration is not yet verified. Some backend services and frontend components are represented by their source paths; relationships are included only where excerpts, the source index, or README support them.

Main entry points: [`backend/main.py`](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/main.py) (FastAPI routes), [`frontend/src/pages/Dashboard.jsx`](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/models.py`](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/models.py) (Water data models), [`backend/serial_bridge.py`](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/serial_bridge.py) (Serial bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web dashboard"]
  node_app["App session gate<br/>[App.jsx]"]
  node_login["Sign in<br/>[LoginPage.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_tank_card["Tank cards<br/>[WebTankCard.jsx]"]
  node_valve_button["Valve controls<br/>[WebValveButton.jsx]"]
  node_alert_badge["Alert badge<br/>[WebAlertBadge.jsx]"]
  node_mini_chart["History chart<br/>[WebMiniChart.jsx]"]
  node_schedule_row["Schedule rows<br/>[WebScheduleRow.jsx]"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI routes<br/>[main.py]"]
  node_serial_bridge["Serial bridge<br/>[serial_bridge.py]"]
  node_websocket["WebSocket manager"]
  node_database_setup["Database setup<br/>[database.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_domain["Water services"]
  node_sensor["Sensor history<br/>[sensor_service.py]"]
  node_schedule["Schedule management"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_alerts["Alert handling<br/>[alert_service.py]"]
  node_valves["Valve commands<br/>[valve_service.py]"]
  node_models["Water data models<br/>[models.py]"]
end

subgraph group_hardware["Controller link"]
  node_arduino["Arduino controller<br/>[water_systems.ino]"]
end

node_operator(("Operator"))
node_mysql[("MySQL database")]

node_operator -->|"opens"| node_app
node_app -->|"shows unauthenticated"| node_login
node_app -->|"shows authenticated"| node_dashboard
node_login -->|"posts credentials"| node_backend
node_dashboard -->|"requests data"| node_api_client
node_dashboard -->|"renders"| node_tank_card
node_dashboard -->|"renders"| node_valve_button
node_dashboard -->|"renders"| node_alert_badge
node_dashboard -->|"renders"| node_mini_chart
node_dashboard -->|"renders"| node_schedule_row
node_api_client -->|"calls HTTP API"| node_backend
node_backend -->|"authenticates"| node_auth
node_backend -->|"reads and saves"| node_sensor
node_backend -->|"manages schedules"| node_schedule
node_backend -->|"loads active alerts"| node_alerts
node_backend -->|"loads valve states"| node_valves
node_backend -->|"broadcasts updates"| node_websocket
node_backend -->|"routes device data"| node_serial_bridge
node_backend -->|"validates payloads"| node_schemas
node_database_setup -->|"initializes tables"| node_mysql
node_database_setup -->|"creates model tables"| node_models
node_sensor -->|"persists readings"| node_models
node_schedule -->|"stores schedules"| node_models
node_auth -.->|"looks up users"| node_models
node_valves -->|"stores commands"| node_models
node_serial_bridge -.->|"forwards readings"| node_backend
node_arduino -.->|"sends readings"| node_serial_bridge
node_serial_bridge -.->|"queues commands"| node_arduino
node_backend -->|"serves live updates"| node_websocket
node_dashboard -.->|"receives live updates"| node_websocket

click node_app "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/App.jsx"
click node_login "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/pages/LoginPage.jsx"
click node_dashboard "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/pages/Dashboard.jsx"
click node_api_client "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/api.js"
click node_tank_card "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebTankCard.jsx"
click node_valve_button "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebValveButton.jsx"
click node_alert_badge "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebAlertBadge.jsx"
click node_mini_chart "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebMiniChart.jsx"
click node_schedule_row "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebScheduleRow.jsx"
click node_backend "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/main.py"
click node_serial_bridge "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/serial_bridge.py"
click node_websocket "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/websocket_manager.py"
click node_database_setup "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/database.py"
click node_schemas "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/schemas.py"
click node_sensor "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/sensor_service.py"
click node_schedule "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/schedule_service.py"
click node_auth "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/auth_service.py"
click node_alerts "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/alert_service.py"
click node_valves "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/valve_service.py"
click node_models "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/models.py"
click node_arduino "https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/arduino/water_systems.ino"

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_login,node_dashboard,node_api_client,node_tank_card,node_valve_button,node_alert_badge,node_mini_chart,node_schedule_row toneBlue
class node_backend,node_serial_bridge,node_websocket,node_database_setup,node_schemas,node_mysql toneAmber
class node_sensor,node_schedule,node_auth,node_alerts,node_valves,node_models toneMint
class node_arduino toneRose
class node_operator toneIndigo
```

## Components

### Web dashboard

- [App session gate](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign in](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`
- [Dashboard](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [API client](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/api.js): `frontend/src/api.js`
- [Tank cards](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebTankCard.jsx): `frontend/src/components/WebTankCard.jsx`
- [Valve controls](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebValveButton.jsx): `frontend/src/components/WebValveButton.jsx`
- [Alert badge](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebAlertBadge.jsx): `frontend/src/components/WebAlertBadge.jsx`
- [History chart](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebMiniChart.jsx): `frontend/src/components/WebMiniChart.jsx`
- [Schedule rows](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/frontend/src/components/WebScheduleRow.jsx): `frontend/src/components/WebScheduleRow.jsx`

### Backend API

- [FastAPI routes](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/main.py): `backend/main.py`
- [Serial bridge](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/serial_bridge.py): `backend/serial_bridge.py`
- [WebSocket manager](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/websocket_manager.py): `backend/websocket_manager.py`
- [Database setup](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/database.py): `backend/database.py`
- [API schemas](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/schemas.py): `backend/schemas.py`

### Water services

- [Sensor history](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/sensor_service.py): `backend/services/sensor_service.py`
- [Schedule management](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/schedule_service.py): `backend/services/schedule_service.py`
- [Authentication](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Alert handling](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/alert_service.py): `backend/services/alert_service.py`
- [Valve commands](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/services/valve_service.py): `backend/services/valve_service.py`
- [Water data models](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/backend/models.py): `backend/models.py`

### Controller link

- [Arduino controller](https://github.com/ryle-kun/project-water-filter-system-v2/blob/dev/arduino/water_systems.ino): `arduino/water_systems.ino`

### Other components

- **Operator**
- **MySQL database**

## Connections

- Operator → App session gate: opens (evidence: `README.md`)
- App session gate → Sign in: shows unauthenticated (evidence: `frontend/src/App.jsx`)
- App session gate → Dashboard: shows authenticated (evidence: `frontend/src/App.jsx`)
- Sign in → FastAPI routes: posts credentials (evidence: `frontend/src/pages/LoginPage.jsx`)
- Dashboard → API client: requests data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Tank cards: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Valve controls: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Alert badge: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → History chart: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Schedule rows: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- API client → FastAPI routes: calls HTTP API (evidence: `README.md`)
- FastAPI routes → Authentication: authenticates (evidence: `backend/main.py`)
- FastAPI routes → Sensor history: reads and saves (evidence: `backend/main.py`)
- FastAPI routes → Schedule management: manages schedules (evidence: `backend/main.py`)
- FastAPI routes → Alert handling: loads active alerts (evidence: `backend/main.py`)
- FastAPI routes → Valve commands: loads valve states (evidence: `backend/main.py`)
- FastAPI routes → WebSocket manager: broadcasts updates (evidence: `backend/main.py`)
- FastAPI routes → Serial bridge: routes device data (evidence: `backend/main.py`)
- FastAPI routes → API schemas: validates payloads (evidence: `backend/main.py`)
- Database setup → MySQL database: initializes tables (evidence: `backend/database.py`)
- Database setup → Water data models: creates model tables (evidence: `backend/database.py`)
- Sensor history → Water data models: persists readings (evidence: `backend/services/sensor_service.py`)
- Schedule management → Water data models: stores schedules (evidence: `backend/services/schedule_service.py`)
- Authentication → Water data models: looks up users
- Valve commands → Water data models: stores commands
- Serial bridge → FastAPI routes: forwards readings (evidence: `README.md`)
- Arduino controller → Serial bridge: sends readings (evidence: `README.md`)
- Serial bridge → Arduino controller: queues commands (evidence: `README.md`)
- FastAPI routes → WebSocket manager: serves live updates (evidence: `README.md`)
- Dashboard → WebSocket manager: receives live updates (evidence: `README.md`)
