# freyderpd07/waterqualitysensors architecture

> Architecture diagram of the GitHub repository freyderpd07/waterqualitysensors, 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/freyderpd07/waterqualitysensors
- Repository: https://github.com/freyderpd07/waterqualitysensors

## Overview

WaterMLdetect monitors community water quality: sensor readings arrive through LoRaWAN/MQTT or direct HTTP, are normalized and classified, stored separately from derived predictions, and exposed through public and authenticated dashboards. Users can also ask HelioWater questions and submit alteration reports; administrators manage reports. The README documents additional dashboard capabilities, including alerting, prediction views, network status, and CSV export. Edges reflect excerpted calls, indexed imports, or README statements; some frontend/API details and unsampled subsystems are documented rather than directly inspected.

Main entry points: [`gateway/src/api.js`](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/api.js) (REST API), [`gateway/src/lecturasRepository.js`](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/lecturasRepository.js) (Raw readings), [`gateway/src/index.js`](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/index.js) (Gateway bootstrap), [`gateway/src/ia.js`](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/ia.js) (HelioWater service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Sensor acquisition"]
  node_sensors{{"LoRaWAN sensors"}}
  node_ttn["TTN / ChirpStack"]
  node_mqtt["MQTT ingestion<br/>[mqtt.js]"]
  node_sensor_http["HTTP sensor intake<br/>[ttnSensor.js]"]
end

subgraph group_gateway["Gateway services"]
  node_server["Gateway bootstrap<br/>[index.js]"]
  node_rest["REST API<br/>[api.js]"]
  node_auth["Accounts and JWT<br/>[auth.js]"]
  node_quality["Quality classification<br/>[calidad.js]"]
  node_reports["Alteration reports<br/>[reportes.js]"]
  node_demo["Demo simulator<br/>[simulador.js]"]
end

subgraph group_data["Water data"]
  node_readings["Raw readings"]
  node_predictions["ML predictions"]
  node_mongo[("MongoDB")]
end

subgraph group_web["Web experience"]
  node_public_page["Public water status<br/>[index.html]"]
  node_dashboard["Authenticated dashboard<br/>[index.js]"]
  node_charts["Dashboard charts<br/>[grafica.js]"]
  node_login["Login and registration<br/>[login.js]"]
  node_profile["Profile management<br/>[perfil.js]"]
  node_chat["HelioWater chat<br/>[chat.js]"]
  node_report_ui["Report workflow<br/>[index.js]"]
end

subgraph group_assistant["AI assistant"]
  node_assistant["HelioWater service<br/>[ia.js]"]
  node_prompt["Assistant prompt<br/>[asistente_agua.md]"]
  node_openrouter["OpenRouter"]
end

node_community(("Community users"))
node_admin(("Administrator"))

node_sensors -->|"sends uplinks"| node_ttn
node_ttn -->|"forwards MQTT"| node_mqtt
node_mqtt -->|"saves readings"| node_readings
node_sensor_http -->|"saves readings"| node_readings
node_server -->|"starts client"| node_mqtt
node_server -->|"registers routes"| node_rest
node_server -->|"registers routes"| node_auth
node_server -->|"registers routes"| node_reports
node_server -->|"registers routes"| node_sensor_http
node_readings -->|"normalizes with"| node_quality
node_readings -->|"registers prediction"| node_predictions
node_predictions -->|"stores predictions"| node_mongo
node_readings -->|"stores readings"| node_mongo
node_rest -->|"queries readings"| node_readings
node_rest -->|"queries predictions"| node_predictions
node_rest -->|"generates alerts"| node_quality
node_rest -->|"uses demo data"| node_demo
node_community -->|"views status"| node_public_page
node_community -->|"views dashboard"| node_dashboard
node_dashboard -->|"requests data"| node_rest
node_public_page -->|"requests status"| node_rest
node_dashboard -.->|"renders charts"| node_charts
node_community -->|"registers or signs in"| node_login
node_login -->|"authenticates"| node_auth
node_community -->|"edits profile"| node_profile
node_profile -.->|"updates account"| node_auth
node_community -->|"asks questions"| node_chat
node_chat -.->|"sends chat request"| node_rest
node_rest -->|"answers questions"| node_assistant
node_assistant -->|"uses thresholds"| node_quality
node_assistant -->|"loads prompt"| node_prompt
node_assistant -.->|"calls model"| node_openrouter
node_community -->|"submits report"| node_report_ui
node_report_ui -.->|"posts report"| node_reports
node_reports -->|"stores reports"| node_mongo
node_admin -->|"reviews reports"| node_reports
node_admin -->|"exports CSV"| node_dashboard

click node_mqtt "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/mqtt.js"
click node_sensor_http "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/ttnSensor.js"
click node_server "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/index.js"
click node_rest "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/api.js"
click node_auth "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/auth.js"
click node_quality "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/calidad.js"
click node_reports "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/reportes.js"
click node_demo "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/simulador.js"
click node_readings "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/lecturasRepository.js"
click node_predictions "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/prediccionesRepository.js"
click node_public_page "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/index.html"
click node_dashboard "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/index.js"
click node_charts "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/grafica.js"
click node_login "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/login.js"
click node_profile "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/perfil.js"
click node_chat "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/chat.js"
click node_report_ui "https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/index.js"
click node_assistant "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/ia.js"
click node_prompt "https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/prompts/asistente_agua.md"

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_sensors,node_ttn,node_mqtt,node_sensor_http,node_community toneBlue
class node_server,node_rest,node_auth,node_quality,node_reports,node_demo toneAmber
class node_readings,node_predictions,node_mongo toneMint
class node_public_page,node_dashboard,node_charts,node_login,node_profile,node_chat,node_report_ui toneRose
class node_assistant,node_prompt,node_openrouter,node_admin toneIndigo
```

## Components

### Sensor acquisition

- **LoRaWAN sensors**
- **TTN / ChirpStack**
- [MQTT ingestion](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/mqtt.js): `gateway/src/mqtt.js`
- [HTTP sensor intake](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/ttnSensor.js): `gateway/src/ttnSensor.js`

### Gateway services

- [Gateway bootstrap](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/index.js): `gateway/src/index.js`
- [REST API](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/api.js): `gateway/src/api.js`
- [Accounts and JWT](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/auth.js): `gateway/src/auth.js`
- [Quality classification](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/calidad.js): `gateway/src/calidad.js`
- [Alteration reports](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/reportes.js): `gateway/src/reportes.js`
- [Demo simulator](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/simulador.js): `gateway/src/simulador.js`

### Water data

- [Raw readings](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/lecturasRepository.js): `gateway/src/lecturasRepository.js`
- [ML predictions](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/prediccionesRepository.js): `gateway/src/prediccionesRepository.js`
- **MongoDB**

### Web experience

- [Public water status](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/index.html): `frontend/index.html`
- [Authenticated dashboard](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/index.js): `frontend/app/index.js`
- [Dashboard charts](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/grafica.js): `frontend/app/grafica.js`
- [Login and registration](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/login.js): `frontend/app/login.js`
- [Profile management](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/perfil.js): `frontend/app/perfil.js`
- [HelioWater chat](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/chat.js): `frontend/app/chat.js`
- [Report workflow](https://github.com/freyderpd07/waterqualitysensors/blob/main/frontend/app/index.js): `frontend/app/index.js`

### AI assistant

- [HelioWater service](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/src/ia.js): `gateway/src/ia.js`
- [Assistant prompt](https://github.com/freyderpd07/waterqualitysensors/blob/main/gateway/prompts/asistente_agua.md): `gateway/prompts/asistente_agua.md`
- **OpenRouter**

### Other components

- **Community users**
- **Administrator**

## Connections

- LoRaWAN sensors → TTN / ChirpStack: sends uplinks (evidence: `README.md`)
- TTN / ChirpStack → MQTT ingestion: forwards MQTT (evidence: `README.md`)
- MQTT ingestion → Raw readings: saves readings (evidence: `gateway/src/mqtt.js`)
- HTTP sensor intake → Raw readings: saves readings (evidence: `gateway/src/ttnSensor.js`)
- Gateway bootstrap → MQTT ingestion: starts client (evidence: `gateway/src/index.js`)
- Gateway bootstrap → REST API: registers routes (evidence: `gateway/src/index.js`)
- Gateway bootstrap → Accounts and JWT: registers routes (evidence: `gateway/src/index.js`)
- Gateway bootstrap → Alteration reports: registers routes (evidence: `gateway/src/index.js`)
- Gateway bootstrap → HTTP sensor intake: registers routes (evidence: `gateway/src/index.js`)
- Raw readings → Quality classification: normalizes with (evidence: `gateway/src/lecturasRepository.js`)
- Raw readings → ML predictions: registers prediction (evidence: `gateway/src/lecturasRepository.js`)
- ML predictions → MongoDB: stores predictions (evidence: `gateway/src/prediccionesRepository.js`)
- Raw readings → MongoDB: stores readings (evidence: `gateway/src/lecturasRepository.js`)
- REST API → Raw readings: queries readings (evidence: `gateway/src/api.js`)
- REST API → ML predictions: queries predictions (evidence: `gateway/src/api.js`)
- REST API → Quality classification: generates alerts (evidence: `gateway/src/api.js`)
- REST API → Demo simulator: uses demo data (evidence: `gateway/src/api.js`)
- Community users → Public water status: views status (evidence: `README.md`)
- Community users → Authenticated dashboard: views dashboard (evidence: `README.md`)
- Authenticated dashboard → REST API: requests data (evidence: `README.md`)
- Public water status → REST API: requests status (evidence: `README.md`)
- Authenticated dashboard → Dashboard charts: renders charts
- Community users → Login and registration: registers or signs in (evidence: `README.md`)
- Login and registration → Accounts and JWT: authenticates (evidence: `README.md`)
- Community users → Profile management: edits profile (evidence: `README.md`)
- Profile management → Accounts and JWT: updates account
- Community users → HelioWater chat: asks questions (evidence: `README.md`)
- HelioWater chat → REST API: sends chat request
- REST API → HelioWater service: answers questions (evidence: `gateway/src/api.js`)
- HelioWater service → Quality classification: uses thresholds (evidence: `gateway/src/ia.js`)
- HelioWater service → Assistant prompt: loads prompt (evidence: `gateway/src/ia.js`)
- HelioWater service → OpenRouter: calls model (evidence: `gateway/src/ia.js`)
- Community users → Report workflow: submits report (evidence: `README.md`)
- Report workflow → Alteration reports: posts report
- Alteration reports → MongoDB: stores reports (evidence: `gateway/src/reportes.js`)
- Administrator → Alteration reports: reviews reports (evidence: `README.md`)
- Administrator → Authenticated dashboard: exports CSV (evidence: `README.md`)
