HydroLabs - Dashboard de Monitoreo de Calidad de Agua

Sistema de monitoreo de calidad de agua en tiempo real para Panama, con enfoque operativo en:

• pH
• Turbidez (NTU)
• TDS (ppm)

Incluye dashboard interactivo, mapa georreferenciado, historicos, exportaciones JSON, generacion de reportes PDF, chatbot con IA, alertas por Discord/Resend y persistencia robusta en base de datos local normalizada (3FN) con sincronizacion opcional a Supabase.

1. Resumen rapido
2. Arquitectura general
3. Frontend en detalle
4. Backend en detalle
5. Base de datos en detalle
6. API HTTP y eventos en tiempo real
7. Variables de entorno (.env)
8. Estructura del proyecto
9. Como ejecutar

• La UI principal se renderiza desde assets/js/ui-shell.js sobre #app-root.
• assets/index.html redirige por defecto a landing.html; para abrir dashboard se usa index.html?dashboard=1.
• El control principal de captura/lectura es un boton toggle unificado:
  • Estado activo: Pausar Captura
  • Estado pausado: Tomar Lectura
• El backend central (python/main.py) expone APIs, sockets, reglas operativas y flujo de persistencia.
• Persistencia en 2 niveles:
  • Series de tiempo (TimeSeriesStore) para graficas y historicos.
  • Modelo 3FN local (SQLStore) para lecturas estructuradas.
• Sincronizacion remota opcional a Supabase por RPC con cola de reintentos local.

Estados de calidad de agua:

• 0 -> Apta (verde)
• 1 -> Tolerable (amarillo)
• 2 -> No apta (rojo)

▶️ Click para ver demo del sistema HydroLabs

flowchart LR
    MCU[Arduino UNO Q<br/>sketch.ino] -->|Bridge.notify| BE[Python Backend<br/>main.py]
    BE -->|Bridge.call| MCU

    BE --> TS[TimeSeriesStore<br/>historial rapido]
    BE --> RS[ReadingStore]
    RS --> L3FN[Local3NFStore<br/>SQLStore water_quality_3nf]
    L3FN --> Q[sync_queue]
    Q --> RS
    RS -->|RPC opcional| SUPA[(Supabase PostgreSQL)]

    BE --> WEB[WebUI + APIs + Socket events]
    WEB --> FE[Frontend Dashboard<br/>app.js + js/*]

    FE --> REP[PDF Reportes]
    FE --> BOT[HydroBot IA]
    BE --> ALERT[Discord + Resend + Telegram]

Patron de navegacion:

• assets/index.html contiene un guard de query (?dashboard=1) para evitar entrar al panel por accidente.
• Header comun en el shell con enlaces a landing, components y dashboard.

• Boton primario toggle:
  • Captura activa -> pausa captura.
  • Captura pausada -> ejecuta lectura y guardado.
• Mensajeria de estado visible:
  • Preview no guardada
  • Guardando
  • Guardado en DB
  • Error
  • Modo prueba
• Feedback de configuracion:
  • Chatbot indica si usa clave local o clave backend (.env).
  • Alertas muestran si Discord/Resend estan listos.
  • Dialogo de reporte deshabilita envio email si Resend no esta configurado.

• Tailwind CSS (via CDN)
• Chart.js
• Leaflet
• jsPDF
• html2canvas
• Socket.IO client
• Lucide icons

sequenceDiagram
    actor U as Operador Web
    participant FE as Frontend
    participant BE as main.py
    participant BR as Bridge
    participant MCU as sketch.ino
    participant TS as TimeSeriesStore
    participant L3 as Local3NFStore
    participant SP as Supabase RPC

    U->>FE: Click boton primario
    FE->>BE: socket "take_reading"
    BE->>BR: Bridge.call("take_reading")
    BR->>MCU: Ejecuta lectura hardware
    MCU->>BR: notify receive_reading(...)
    BR->>BE: Callback receive_reading
    BE->>TS: write_sample(...) por metrica
    BE->>L3: save_reading(payload)
    BE->>SP: push RPC (si habilitado)
    BE-->>FE: reading_update + estados
    FE-->>U: tarjetas, tabla, historial y mapa actualizados

• OpenRouter (/chat) para HydroBot.
• Resend (/send_report y alertas email).
• Discord webhook (/test_notifications y alertas criticas).
• Telegram bot (/test_notifications con chat_id opcional, o con chats registrados/whitelist).
• Telegram bot (comandos operativos: estado, lectura, captura, ubicacion).

• TEST_MODE=true: UI con mocks, sin persistencia real.
• Validaciones de placeholders para evitar considerar credenciales falsas como configuradas.
• Control de frecuencia minima entre lecturas (MIN_TAKE_READING_GAP_S).
• Temporizador de calibracion por ubicacion (SENSOR_CALIBRATION_S).

La persistencia se diseña en capas para resiliencia y trazabilidad.

• Guarda series por recurso (ph_*, ntu_*, tds_*, estado_*, etc.).
• Se usa para graficas y paneles de historial.

Base local: water_quality_3nf

Tablas principales:

• locations
• devices
• metric_types
• readings
• reading_metrics
• sync_queue

Ventajas:

• Lectura estructurada por entidad y metrica.
• Indices para consultas por ubicacion/tiempo.
• Cola local para sincronizacion diferida.

• Si SUPABASE_SYNC_ENABLED=true y credenciales validas:
  • ReadingStore invoca RPC ingest_water_reading.
• Si falla red/credencial:
  • La lectura queda en sync_queue local.
  • Se reintenta automaticamente desde el loop.

erDiagram
    LOCATIONS ||--o{ READINGS : contiene
    DEVICES ||--o{ READINGS : genera
    READINGS ||--o{ READING_METRICS : desglosa
    METRIC_TYPES ||--o{ READING_METRICS : tipifica
    READINGS ||--o| SYNC_QUEUE : pendiente_sync

    LOCATIONS {
      int id PK
      string location_key UK
      string name
      float lat
      float lon
    }

    DEVICES {
      int id PK
      string device_uid UK
      string board_model
      string firmware_version
      datetime created_at
    }

    METRIC_TYPES {
      int id PK
      string code UK
      string unit
      string description
    }

    READINGS {
      int id PK
      int location_id FK
      int device_id FK
      int status
      int measured_at_ms
      datetime created_at
    }

    READING_METRICS {
      int reading_id PK,FK
      int metric_type_id PK,FK
      float metric_value
    }

    SYNC_QUEUE {
      int id PK
      int reading_id UK,FK
      string payload_json
      int attempts
      string last_error
      datetime created_at
      datetime updated_at
    }

Archivo: python/.env

Para pruebas por API:

• POST /test_notifications usa Telegram automáticamente si hay chat_id conocido.
• Puedes pasar telegram_chat_id (o chat_id) en el body para forzar el destino en esa prueba.

dashboard/
  assets/
    index.html
    landing.html
    components.html
    app.js
    style.css
    js/
      api.js
      charts.js
      domain.js
      ui-shell.js
      reports.js
      chatbot.js
  python/
    main.py
    config.py
    domain.py
    repository.py
    reading_store.py
    alerts.py
    requirements.txt
    supabase.sql
  sketch/
    sketch.ino
  app.yaml

1. Abre el proyecto en Arduino App Lab.
2. Configura python/.env con tus credenciales reales.
3. Conecta Arduino UNO Q y sensores en pines definidos.
4. Ejecuta la app.
5. Abre:
   • landing.html para portada
   • index.html?dashboard=1 para operacion

Instalar desde:

• python/requirements.txt

Dependencias clave:

• requests
• resend
• psutil

Esta version productiva esta centrada en sensores de calidad de agua:

• pH
• Turbidez (NTU)
• TDS (ppm)

La arquitectura ya contempla expansion futura, pero el alcance operativo actual se valida con ese set de sensores.