# rachorachelirene-beep/aquaguard architecture

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

- Interactive diagram: https://gitdiagram.com/rachorachelirene-beep/aquaguard
- Repository: https://github.com/rachorachelirene-beep/aquaguard

## Overview

AquaGuard combines role-based flood operations in a React portal with a local camera agent. The user workflow runs from role-scoped access to monitoring and community/response actions; the agent supplies camera telemetry, water-level estimates, and risk indicators, while cloud services provide persistent data and weather. The tree and README establish major capabilities, but many frontend pages and the agent entry point were not excerpted, so their internal call links are omitted or shown only where documentation supports them.

Main entry points: [`detector/stream_api.py`](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/stream_api.py) (Stream and telemetry API), [`src/App.jsx`](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/App.jsx) (Role-based routing), [`src/pages/admin`](https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/admin) (Admin workspace), [`src/components/layouts/DashboardLayout.jsx`](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/components/layouts/DashboardLayout.jsx) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Web portal"]
  node_auth["Authentication and roles<br/>[AuthContext.jsx]"]
  node_routing["Role-based routing<br/>[App.jsx]"]
  node_workspace["Dashboard shell"]
  node_alertaudio["Alert audio and banners"]
  node_detectionhook["Realtime detection client"]
  node_camera_client["Camera agent client<br/>[cameraAgent.js]"]
  node_supabase_client["Browser Supabase client<br/>[supabase.js]"]
end

subgraph group_operations["Flood operations"]
  node_admin["Admin workspace"]
  node_officer["Officer workspace"]
  node_responder["Responder workspace"]
  node_resident["Resident workspace"]
end

subgraph group_agent["Camera agent"]
  node_agent_entry["Agent runtime"]
  node_stream["Stream and telemetry API<br/>[stream_api.py]"]
  node_vision["YOLO flood detection<br/>[stream_api.py]"]
  node_gauge["Virtual gauge estimation<br/>[gauge.py]"]
  node_risk["Flood risk rules<br/>[flood_risk.py]"]
  node_camera_config["Camera configuration<br/>[camera_config.py]"]
  node_agent_auth["Agent authorization<br/>[admin_auth.py]"]
  node_weather_sync["Weather synchronization<br/>[weather_service.py]"]
end

subgraph group_services["Cloud services"]
  node_supabase[("Supabase data, auth, realtime")]
  node_openmeteo["Open-Meteo"]
end

node_user(("Portal user"))
node_cameras(("USB / RTSP cameras"))

node_user -->|"opens portal"| node_routing
node_routing -->|"checks session"| node_auth
node_routing -->|"routes admin"| node_admin
node_routing -->|"routes officer"| node_officer
node_routing -->|"routes responder"| node_responder
node_routing -->|"routes resident"| node_resident
node_admin -.->|"renders layout"| node_workspace
node_officer -.->|"renders layout"| node_workspace
node_responder -.->|"renders layout"| node_workspace
node_resident -.->|"renders layout"| node_workspace
node_workspace -->|"reads alert state"| node_alertaudio
node_alertaudio -->|"subscribes to alerts"| node_supabase
node_admin -.->|"manages system data"| node_supabase
node_officer -.->|"coordinates operations"| node_supabase
node_responder -.->|"records response"| node_supabase
node_resident -.->|"reads public information"| node_supabase
node_supabase_client -->|"connects"| node_supabase
node_admin -->|"configures agent"| node_camera_client
node_camera_client -->|"targets local agent"| node_agent_entry
node_agent_entry -.->|"starts API"| node_stream
node_cameras -->|"provides video"| node_agent_entry
node_stream -->|"processes frames"| node_vision
node_stream -->|"estimates level"| node_gauge
node_stream -->|"calculates indicators"| node_risk
node_stream -->|"loads camera settings"| node_camera_config
node_stream -->|"checks admin access"| node_agent_auth
node_stream -.->|"starts weather worker"| node_weather_sync
node_weather_sync -->|"fetches conditions"| node_openmeteo
node_weather_sync -->|"stores telemetry"| node_supabase
node_stream -.->|"syncs detections"| node_supabase
node_admin -->|"monitors detection"| node_detectionhook
node_resident -->|"reads live detection"| node_detectionhook
node_detectionhook -.->|"connects to agent"| node_camera_client
node_responder -->|"requests risk data"| node_camera_client

click node_auth "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/context/AuthContext.jsx"
click node_routing "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/App.jsx"
click node_workspace "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/components/layouts/DashboardLayout.jsx"
click node_admin "https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/admin"
click node_officer "https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/officer"
click node_responder "https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/responder"
click node_resident "https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/resident"
click node_alertaudio "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/context/AlertAudioContext.jsx"
click node_detectionhook "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/hooks/useRealtimeDetection.js"
click node_camera_client "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/lib/cameraAgent.js"
click node_agent_entry "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/run_camera_agent.py"
click node_stream "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/stream_api.py"
click node_vision "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/stream_api.py"
click node_gauge "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/gauge.py"
click node_risk "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/flood_risk.py"
click node_camera_config "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/camera_config.py"
click node_agent_auth "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/admin_auth.py"
click node_weather_sync "https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/weather_service.py"
click node_supabase_client "https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/lib/supabase.js"

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_auth,node_routing,node_workspace,node_alertaudio,node_detectionhook,node_camera_client,node_supabase_client,node_user toneBlue
class node_admin,node_officer,node_responder,node_resident toneAmber
class node_agent_entry,node_stream,node_vision,node_gauge,node_risk,node_camera_config,node_agent_auth,node_weather_sync toneMint
class node_supabase,node_openmeteo toneRose
class node_cameras toneIndigo
```

## Components

### Web portal

- [Authentication and roles](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Role-based routing](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/App.jsx): `src/App.jsx`
- [Dashboard shell](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/components/layouts/DashboardLayout.jsx): `src/components/layouts/DashboardLayout.jsx`
- [Alert audio and banners](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/context/AlertAudioContext.jsx): `src/context/AlertAudioContext.jsx`
- [Realtime detection client](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/hooks/useRealtimeDetection.js): `src/hooks/useRealtimeDetection.js`
- [Camera agent client](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/lib/cameraAgent.js): `src/lib/cameraAgent.js`
- [Browser Supabase client](https://github.com/rachorachelirene-beep/aquaguard/blob/main/src/lib/supabase.js): `src/lib/supabase.js`

### Flood operations

- [Admin workspace](https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/admin): `src/pages/admin`
- [Officer workspace](https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/officer): `src/pages/officer`
- [Responder workspace](https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/responder): `src/pages/responder`
- [Resident workspace](https://github.com/rachorachelirene-beep/aquaguard/tree/main/src/pages/resident): `src/pages/resident`

### Camera agent

- [Agent runtime](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/run_camera_agent.py): `detector/run_camera_agent.py`
- [Stream and telemetry API](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/stream_api.py): `detector/stream_api.py`
- [YOLO flood detection](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/stream_api.py): `detector/stream_api.py`
- [Virtual gauge estimation](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/gauge.py): `detector/gauge.py`
- [Flood risk rules](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/flood_risk.py): `detector/flood_risk.py`
- [Camera configuration](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/camera_config.py): `detector/camera_config.py`
- [Agent authorization](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/admin_auth.py): `detector/admin_auth.py`
- [Weather synchronization](https://github.com/rachorachelirene-beep/aquaguard/blob/main/detector/weather_service.py): `detector/weather_service.py`

### Cloud services

- **Supabase data, auth, realtime**
- **Open-Meteo**

### Other components

- **Portal user**
- **USB / RTSP cameras**

## Connections

- Portal user → Role-based routing: opens portal (evidence: `README.md`)
- Role-based routing → Authentication and roles: checks session (evidence: `src/App.jsx`)
- Role-based routing → Admin workspace: routes admin (evidence: `src/App.jsx`)
- Role-based routing → Officer workspace: routes officer (evidence: `src/App.jsx`)
- Role-based routing → Responder workspace: routes responder (evidence: `src/App.jsx`)
- Role-based routing → Resident workspace: routes resident (evidence: `src/App.jsx`)
- Admin workspace → Dashboard shell: renders layout (evidence: `src/pages/admin/CameraSettings.jsx`)
- Officer workspace → Dashboard shell: renders layout (evidence: `src/pages/officer/OfficerDashboard.jsx`)
- Responder workspace → Dashboard shell: renders layout (evidence: `src/pages/responder/ResponderDashboard.jsx`)
- Resident workspace → Dashboard shell: renders layout (evidence: `src/pages/resident/ResidentDashboard.jsx`)
- Dashboard shell → Alert audio and banners: reads alert state (evidence: `src/components/layouts/DashboardLayout.jsx`)
- Alert audio and banners → Supabase data, auth, realtime: subscribes to alerts (evidence: `src/context/AlertAudioContext.jsx`)
- Admin workspace → Supabase data, auth, realtime: manages system data
- Officer workspace → Supabase data, auth, realtime: coordinates operations
- Responder workspace → Supabase data, auth, realtime: records response
- Resident workspace → Supabase data, auth, realtime: reads public information
- Browser Supabase client → Supabase data, auth, realtime: connects (evidence: `src/lib/supabase.js`)
- Admin workspace → Camera agent client: configures agent (evidence: `src/pages/admin/CameraSettings.jsx`)
- Camera agent client → Agent runtime: targets local agent (evidence: `README.md`)
- Agent runtime → Stream and telemetry API: starts API
- USB / RTSP cameras → Agent runtime: provides video (evidence: `README.md`)
- Stream and telemetry API → YOLO flood detection: processes frames (evidence: `README.md`)
- Stream and telemetry API → Virtual gauge estimation: estimates level (evidence: `detector/stream_api.py`)
- Stream and telemetry API → Flood risk rules: calculates indicators (evidence: `detector/stream_api.py`)
- Stream and telemetry API → Camera configuration: loads camera settings (evidence: `detector/stream_api.py`)
- Stream and telemetry API → Agent authorization: checks admin access (evidence: `detector/stream_api.py`)
- Stream and telemetry API → Weather synchronization: starts weather worker (evidence: `detector/stream_api.py`)
- Weather synchronization → Open-Meteo: fetches conditions (evidence: `detector/weather_service.py`)
- Weather synchronization → Supabase data, auth, realtime: stores telemetry (evidence: `detector/weather_service.py`)
- Stream and telemetry API → Supabase data, auth, realtime: syncs detections
- Admin workspace → Realtime detection client: monitors detection (evidence: `src/pages/admin/LiveMonitoring.jsx`)
- Resident workspace → Realtime detection client: reads live detection (evidence: `src/pages/resident/ResidentDashboard.jsx`)
- Realtime detection client → Camera agent client: connects to agent
- Responder workspace → Camera agent client: requests risk data (evidence: `src/pages/responder/ResponderDashboard.jsx`)
