# tktarun03/chennai-waterguard-ai-poc architecture

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

- Interactive diagram: https://gitdiagram.com/tktarun03/chennai-waterguard-ai-poc
- Repository: https://github.com/tktarun03/chennai-waterguard-ai-poc

## Overview

WaterGuard-AI is a synthetic-data water-governance dashboard, not a live utility integration. The primary path is synthetic telemetry and scenario generation through backend ingestion, anomaly detection, incident/safety assessment, and API responses to citizen/operator dashboard panels; separate branches cover simulated lab verification, building hygiene, authentication, and auditability. Edges are limited to relationships shown by the README or SOURCE INDEX; unsampled route and service internals are represented without speculative wiring.

Main entry points: [`backend/app/workers/synthetic.py`](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/workers/synthetic.py) (Synthetic worker), [`backend/app/api/v1/router.py`](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/router.py) (API v1 router), [`backend/app/services/telemetry.py`](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/telemetry.py) (Telemetry ingestion), [`backend/app/models/entities.py`](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/models/entities.py) (WaterGuard database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard shell<br/>[App.tsx]"]
  node_authui["Sign-in and roles<br/>[useAuth.tsx]"]
  node_client["Typed API client<br/>[api.ts]"]
  node_display["Dashboard panels"]
  node_primitives["UI primitives<br/>[primitives.tsx]"]
  node_format["Display formatting<br/>[format.ts]"]
end

subgraph group_api["API and access"]
  node_router["API v1 router<br/>[router.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_safetyroutes["Safety routes<br/>[safety.py]"]
  node_telemetryroutes["Telemetry routes<br/>[telemetry.py]"]
  node_systemroutes["System routes<br/>[system.py]"]
  node_accounts["Account service<br/>[accounts.py]"]
end

subgraph group_domain["Monitoring and response"]
  node_telemetry["Telemetry ingestion<br/>[telemetry.py]"]
  node_detection["Anomaly detection<br/>[detection.py]"]
  node_assessment["Safety assessment<br/>[assessment.py]"]
  node_safemeter["Safe Meter engine<br/>[safe_meter.py]"]
  node_incidents["Incident lifecycle<br/>[incidents.py]"]
  node_laboratory["Lab verification<br/>[laboratory.py]"]
  node_hygiene["Building hygiene<br/>[hygiene.py]"]
end

subgraph group_sim["Synthetic operations"]
  node_scenarios["Scenario controls<br/>[scenarios.py]"]
  node_worker["Synthetic worker<br/>[synthetic.py]"]
  node_simulator["Sensor generator"]
end

subgraph group_data["Persistence and foundations"]
  node_database[("WaterGuard database<br/>[entities.py]")]
  node_session["Database sessions<br/>[session.py]"]
  node_enums["Domain state types<br/>[enums.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_citizen(("Citizen / operator"))

node_citizen -->|"views"| node_dashboard
node_dashboard -->|"requests data"| node_client
node_dashboard -->|"renders"| node_display
node_display -->|"requests data"| node_client
node_display -->|"formats values"| node_format
node_display -->|"renders"| node_primitives
node_authui -->|"authenticates"| node_client
node_client -->|"calls API"| node_router
node_router -->|"registers"| node_authroutes
node_router -->|"registers"| node_safetyroutes
node_router -->|"registers"| node_telemetryroutes
node_systemroutes -.->|"mounts routes"| node_router
node_authroutes -->|"delegates to"| node_accounts
node_telemetryroutes -.->|"delegates to"| node_telemetry
node_safetyroutes -.->|"delegates to"| node_safemeter
node_telemetry -->|"evaluates readings"| node_detection
node_telemetry -->|"creates incidents"| node_incidents
node_safemeter -->|"uses signals"| node_detection
node_assessment -.->|"assesses safety"| node_safemeter
node_incidents -.->|"requests verification"| node_laboratory
node_worker -->|"submits readings"| node_telemetry
node_worker -->|"runs scenarios"| node_scenarios
node_worker -->|"runs assessment"| node_assessment
node_worker -->|"checks hygiene"| node_hygiene
node_simulator -.->|"supplies synthetic data"| node_worker
node_telemetry -.->|"stores readings"| node_database
node_incidents -.->|"stores incidents"| node_database
node_hygiene -.->|"stores hygiene records"| node_database
node_session -->|"provides sessions"| node_database
node_database -->|"uses domain states"| node_enums
node_config -->|"configures database"| node_session
node_config -->|"configures logging"| node_logging
node_accounts -.->|"records events"| node_logging

click node_dashboard "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/hooks/useAuth.tsx"
click node_client "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/lib/api.ts"
click node_display "https://github.com/tktarun03/chennai-waterguard-ai-poc/tree/main/frontend/src/components"
click node_primitives "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/components/primitives.tsx"
click node_format "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/lib/format.ts"
click node_router "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/router.py"
click node_authroutes "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/auth.py"
click node_safetyroutes "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/safety.py"
click node_telemetryroutes "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/telemetry.py"
click node_systemroutes "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/system.py"
click node_accounts "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/accounts.py"
click node_telemetry "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/telemetry.py"
click node_detection "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/detection.py"
click node_assessment "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/assessment.py"
click node_safemeter "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/safe_meter.py"
click node_incidents "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/incidents.py"
click node_laboratory "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/laboratory.py"
click node_hygiene "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/hygiene.py"
click node_scenarios "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/scenarios.py"
click node_worker "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/workers/synthetic.py"
click node_simulator "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/simulator/sensor_generator.py"
click node_database "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/models/entities.py"
click node_session "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/db/session.py"
click node_enums "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/models/enums.py"
click node_logging "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/core/logging.py"
click node_config "https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/core/config.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_dashboard,node_authui,node_client,node_display,node_primitives,node_format toneBlue
class node_router,node_authroutes,node_safetyroutes,node_telemetryroutes,node_systemroutes,node_accounts toneAmber
class node_telemetry,node_detection,node_assessment,node_safemeter,node_incidents,node_laboratory,node_hygiene toneMint
class node_scenarios,node_worker,node_simulator toneRose
class node_database,node_session,node_enums,node_logging,node_config,node_citizen toneIndigo
```

## Components

### Dashboard

- [Dashboard shell](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in and roles](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/hooks/useAuth.tsx): `frontend/src/hooks/useAuth.tsx`
- [Typed API client](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Dashboard panels](https://github.com/tktarun03/chennai-waterguard-ai-poc/tree/main/frontend/src/components): `frontend/src/components`
- [UI primitives](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/components/primitives.tsx): `frontend/src/components/primitives.tsx`
- [Display formatting](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/frontend/src/lib/format.ts): `frontend/src/lib/format.ts`

### API and access

- [API v1 router](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication routes](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Safety routes](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/safety.py): `backend/app/api/v1/safety.py`
- [Telemetry routes](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/telemetry.py): `backend/app/api/v1/telemetry.py`
- [System routes](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/api/v1/system.py): `backend/app/api/v1/system.py`
- [Account service](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/accounts.py): `backend/app/services/accounts.py`

### Monitoring and response

- [Telemetry ingestion](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/telemetry.py): `backend/app/services/telemetry.py`
- [Anomaly detection](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/detection.py): `backend/app/services/detection.py`
- [Safety assessment](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/assessment.py): `backend/app/services/assessment.py`
- [Safe Meter engine](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/safe_meter.py): `backend/app/services/safe_meter.py`
- [Incident lifecycle](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/incidents.py): `backend/app/services/incidents.py`
- [Lab verification](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/laboratory.py): `backend/app/services/laboratory.py`
- [Building hygiene](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/hygiene.py): `backend/app/services/hygiene.py`

### Synthetic operations

- [Scenario controls](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/services/scenarios.py): `backend/app/services/scenarios.py`
- [Synthetic worker](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/workers/synthetic.py): `backend/app/workers/synthetic.py`
- [Sensor generator](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/simulator/sensor_generator.py): `simulator/sensor_generator.py`

### Persistence and foundations

- [WaterGuard database](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/models/entities.py): `backend/app/models/entities.py`
- [Database sessions](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Domain state types](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/models/enums.py): `backend/app/models/enums.py`
- [Structured logging](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/core/logging.py): `backend/app/core/logging.py`
- [Runtime configuration](https://github.com/tktarun03/chennai-waterguard-ai-poc/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Citizen / operator**

## Connections

- Citizen / operator → Dashboard shell: views (evidence: `README.md`)
- Dashboard shell → Typed API client: requests data (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Dashboard panels: renders (evidence: `frontend/src/App.tsx`)
- Dashboard panels → Typed API client: requests data (evidence: `frontend/src/components/IncidentPanel.tsx`)
- Dashboard panels → Display formatting: formats values (evidence: `frontend/src/components/IncidentPanel.tsx`)
- Dashboard panels → UI primitives: renders (evidence: `frontend/src/components/IncidentPanel.tsx`)
- Sign-in and roles → Typed API client: authenticates (evidence: `frontend/src/hooks/useAuth.tsx`)
- Typed API client → API v1 router: calls API (evidence: `README.md`)
- API v1 router → Authentication routes: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 router → Safety routes: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 router → Telemetry routes: registers (evidence: `backend/app/api/v1/router.py`)
- System routes → API v1 router: mounts routes
- Authentication routes → Account service: delegates to (evidence: `backend/app/api/v1/auth.py`)
- Telemetry routes → Telemetry ingestion: delegates to
- Safety routes → Safe Meter engine: delegates to
- Telemetry ingestion → Anomaly detection: evaluates readings (evidence: `backend/app/services/telemetry.py`)
- Telemetry ingestion → Incident lifecycle: creates incidents (evidence: `backend/app/services/telemetry.py`)
- Safe Meter engine → Anomaly detection: uses signals (evidence: `backend/app/services/safe_meter.py`)
- Safety assessment → Safe Meter engine: assesses safety
- Incident lifecycle → Lab verification: requests verification
- Synthetic worker → Telemetry ingestion: submits readings (evidence: `backend/app/workers/synthetic.py`)
- Synthetic worker → Scenario controls: runs scenarios (evidence: `backend/app/workers/synthetic.py`)
- Synthetic worker → Safety assessment: runs assessment (evidence: `backend/app/workers/synthetic.py`)
- Synthetic worker → Building hygiene: checks hygiene (evidence: `backend/app/workers/synthetic.py`)
- Sensor generator → Synthetic worker: supplies synthetic data
- Telemetry ingestion → WaterGuard database: stores readings (evidence: `backend/app/services/telemetry.py`)
- Incident lifecycle → WaterGuard database: stores incidents
- Building hygiene → WaterGuard database: stores hygiene records (evidence: `backend/app/services/hygiene.py`)
- Database sessions → WaterGuard database: provides sessions (evidence: `backend/app/db/session.py`)
- WaterGuard database → Domain state types: uses domain states (evidence: `backend/app/models/entities.py`)
- Runtime configuration → Database sessions: configures database (evidence: `backend/app/db/session.py`)
- Runtime configuration → Structured logging: configures logging (evidence: `backend/app/core/logging.py`)
- Account service → Structured logging: records events (evidence: `backend/app/services/accounts.py`)
