# nnaajjeebb12/i-pond-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/nnaajjeebb12/i-pond-frontend
- Repository: https://github.com/nnaajjeebb12/i-pond-frontend

## Overview

Soletronix iPond is a multi-tenant aquaculture monitoring platform. ESP32 gateways submit sensor readings; authenticated pond owners and viewers inspect live status, historical charts, alerts, maintenance, utilization, and reports, while administrators manage users and ponds. The main data path is sensor ingestion into PostgreSQL/TimescaleDB, followed by role-scoped API queries and dashboard views. The graph preserves documented feature areas even where route or page implementations were not sampled; those links cite the README. Source-level edges are limited to relationships shown in excerpts or the SOURCE INDEX.

Main entry points: [`src/lib/db.ts`](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/db.ts) (Database pool), [`src/auth.ts`](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/auth.ts) (Credentials authentication), [`src/app/api/send-sensor-data/route.ts`](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/send-sensor-data/route.ts) (Sensor ingest), [`src/app/dashboard`](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/dashboard) (Pond dashboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Sensor ingestion"]
  node_sensor_ingest["Sensor ingest<br/>[route.ts]"]
  node_pi_sync["Pi sync receiver<br/>[route.ts]"]
end

subgraph group_data["Pond data"]
  node_readings_api["Readings API<br/>[route.ts]"]
  node_pond_api["Pond status API<br/>[route.ts]"]
  node_readings_extra["Reading queries"]
  node_utilization["Utilization API<br/>[route.ts]"]
  node_threshold_api["Threshold management<br/>[route.ts]"]
  node_database[("TimescaleDB")]
  node_db_pool["Database pool<br/>[db.ts]"]
  node_status_logic["Pond status logic<br/>[pondStatus.ts]"]
end

subgraph group_experience["Monitoring experience"]
  node_dashboard["Pond dashboards"]
  node_charts["Sensor charts<br/>[SensorChart.tsx]"]
  node_api_hooks["Polling data hooks<br/>[useApi.ts]"]
  node_alert_hook["Alert polling<br/>[useAlerts.ts]"]
  node_reports["PDF and CSV reports"]
  node_layout["Application shell<br/>[MainLayout.tsx]"]
  node_utilization_page["Utilization view<br/>[page.tsx]"]
  node_threshold_page["Threshold settings<br/>[page.tsx]"]
  node_notifications["Notifications view<br/>[page.tsx]"]
end

subgraph group_operations["Administration and operations"]
  node_alerts["Alerts"]
  node_alert_logic["Alert logic<br/>[alerts.ts]"]
  node_maintenance["Maintenance workflows"]
  node_admin["Admin management"]
end

subgraph group_identity["Identity and access"]
  node_admin_guard["Admin guard<br/>[admin.ts]"]
  node_auth["Credentials authentication<br/>[auth.ts]"]
  node_auth_config["Auth configuration<br/>[auth.config.ts]"]
  node_auth_ui["Login and session UI<br/>[page.tsx]"]
  node_auth_store["Client auth state<br/>[authStore.ts]"]
end

node_gateway(("ESP32 gateway"))
node_users(("Pond users"))

node_gateway -->|"sends readings"| node_sensor_ingest
node_sensor_ingest -->|"writes readings"| node_db_pool
node_pi_sync -->|"writes readings"| node_db_pool
node_sensor_ingest -->|"stores readings"| node_database
node_pi_sync -->|"stores readings"| node_database
node_readings_api -->|"queries readings"| node_db_pool
node_pond_api -->|"queries pond data"| node_db_pool
node_readings_extra -->|"serves reading queries"| node_database
node_utilization -->|"queries uptime"| node_db_pool
node_threshold_api -->|"reads and updates"| node_db_pool
node_db_pool -->|"connects to"| node_database
node_dashboard -->|"loads monitoring data"| node_api_hooks
node_api_hooks -->|"polls readings"| node_readings_api
node_dashboard -->|"visualizes readings"| node_charts
node_pond_api -->|"uses status rules"| node_status_logic
node_users -->|"views assigned ponds"| node_dashboard
node_alerts -->|"queries alerts"| node_db_pool
node_alert_logic -->|"checks alert data"| node_db_pool
node_alert_hook -->|"polls and acknowledges"| node_alerts
node_maintenance -->|"stores requests"| node_db_pool
node_reports -.->|"exports readings"| node_readings_extra
node_admin -->|"manages records"| node_db_pool
node_admin -->|"checks permissions"| node_admin_guard
node_admin_guard -->|"checks admin role"| node_auth
node_auth -->|"loads credentials"| node_db_pool
node_auth -->|"extends options"| node_auth_config
node_auth_ui -.->|"signs in"| node_auth
node_layout -->|"uses session state"| node_auth_store
node_layout -->|"uses alert polling"| node_alert_hook
node_utilization_page -.->|"requests utilization"| node_utilization
node_threshold_page -.->|"configures thresholds"| node_threshold_api
node_notifications -.->|"handles maintenance"| node_maintenance
node_notifications -.->|"shows alerts"| node_alerts

click node_sensor_ingest "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/send-sensor-data/route.ts"
click node_pi_sync "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/sync/route.ts"
click node_readings_api "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/readings/route.ts"
click node_pond_api "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/ponds/status/route.ts"
click node_readings_extra "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/readings"
click node_utilization "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/utilization/route.ts"
click node_threshold_api "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/thresholds/route.ts"
click node_db_pool "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/db.ts"
click node_dashboard "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/dashboard"
click node_charts "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/components/charts/SensorChart.tsx"
click node_api_hooks "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/hooks/useApi.ts"
click node_status_logic "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/pondStatus.ts"
click node_alerts "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/alerts"
click node_alert_logic "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/alerts.ts"
click node_alert_hook "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/hooks/useAlerts.ts"
click node_maintenance "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/maintenance"
click node_reports "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/reports"
click node_admin "https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/admin"
click node_admin_guard "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/admin.ts"
click node_auth "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/auth.ts"
click node_auth_config "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/auth.config.ts"
click node_auth_ui "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/login/page.tsx"
click node_layout "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/components/MainLayout.tsx"
click node_auth_store "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/store/authStore.ts"
click node_utilization_page "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/utilization/page.tsx"
click node_threshold_page "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/settings/thresholds/page.tsx"
click node_notifications "https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/notifications/page.tsx"

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_sensor_ingest,node_pi_sync,node_users toneBlue
class node_readings_api,node_pond_api,node_readings_extra,node_utilization,node_threshold_api,node_database,node_db_pool,node_status_logic toneAmber
class node_dashboard,node_charts,node_api_hooks,node_alert_hook,node_reports,node_layout,node_utilization_page,node_threshold_page,node_notifications toneMint
class node_alerts,node_alert_logic,node_maintenance,node_admin toneRose
class node_admin_guard,node_auth,node_auth_config,node_auth_ui,node_auth_store,node_gateway toneIndigo
```

## Components

### Sensor ingestion

- [Sensor ingest](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/send-sensor-data/route.ts): `src/app/api/send-sensor-data/route.ts`
- [Pi sync receiver](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/sync/route.ts): `src/app/api/sync/route.ts`

### Pond data

- [Readings API](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/readings/route.ts): `src/app/api/readings/route.ts`
- [Pond status API](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/ponds/status/route.ts): `src/app/api/ponds/status/route.ts`
- [Reading queries](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/readings): `src/app/api/readings`
- [Utilization API](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/utilization/route.ts): `src/app/api/utilization/route.ts`
- [Threshold management](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/api/thresholds/route.ts): `src/app/api/thresholds/route.ts`
- **TimescaleDB**
- [Database pool](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Pond status logic](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/pondStatus.ts): `src/lib/pondStatus.ts`

### Monitoring experience

- [Pond dashboards](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/dashboard): `src/app/dashboard`
- [Sensor charts](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/components/charts/SensorChart.tsx): `src/components/charts/SensorChart.tsx`
- [Polling data hooks](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/hooks/useApi.ts): `src/hooks/useApi.ts`
- [Alert polling](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/hooks/useAlerts.ts): `src/hooks/useAlerts.ts`
- [PDF and CSV reports](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/reports): `src/app/reports`
- [Application shell](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/components/MainLayout.tsx): `src/components/MainLayout.tsx`
- [Utilization view](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/utilization/page.tsx): `src/app/utilization/page.tsx`
- [Threshold settings](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/settings/thresholds/page.tsx): `src/app/settings/thresholds/page.tsx`
- [Notifications view](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/notifications/page.tsx): `src/app/notifications/page.tsx`

### Administration and operations

- [Alerts](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/alerts): `src/app/api/alerts`
- [Alert logic](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/alerts.ts): `src/lib/alerts.ts`
- [Maintenance workflows](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/maintenance): `src/app/api/maintenance`
- [Admin management](https://github.com/nnaajjeebb12/i-pond-frontend/tree/main/src/app/api/admin): `src/app/api/admin`

### Identity and access

- [Admin guard](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/lib/admin.ts): `src/lib/admin.ts`
- [Credentials authentication](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/auth.ts): `src/auth.ts`
- [Auth configuration](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/auth.config.ts): `src/auth.config.ts`
- [Login and session UI](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Client auth state](https://github.com/nnaajjeebb12/i-pond-frontend/blob/main/src/store/authStore.ts): `src/store/authStore.ts`

### Other components

- **ESP32 gateway**
- **Pond users**

## Connections

- ESP32 gateway → Sensor ingest: sends readings
- Sensor ingest → Database pool: writes readings (evidence: `src/app/api/send-sensor-data/route.ts`)
- Pi sync receiver → Database pool: writes readings (evidence: `src/app/api/sync/route.ts`)
- Sensor ingest → TimescaleDB: stores readings
- Pi sync receiver → TimescaleDB: stores readings (evidence: `src/app/api/sync/route.ts`)
- Readings API → Database pool: queries readings (evidence: `src/app/api/readings/route.ts`)
- Pond status API → Database pool: queries pond data (evidence: `src/app/api/ponds/status/route.ts`)
- Reading queries → TimescaleDB: serves reading queries
- Utilization API → Database pool: queries uptime (evidence: `src/app/api/utilization/route.ts`)
- Threshold management → Database pool: reads and updates (evidence: `src/app/api/thresholds/route.ts`)
- Database pool → TimescaleDB: connects to
- Pond dashboards → Polling data hooks: loads monitoring data
- Polling data hooks → Readings API: polls readings (evidence: `src/hooks/useApi.ts`)
- Pond dashboards → Sensor charts: visualizes readings
- Pond status API → Pond status logic: uses status rules (evidence: `src/app/api/ponds/status/route.ts`)
- Pond users → Pond dashboards: views assigned ponds
- Alerts → Database pool: queries alerts (evidence: `src/app/api/alerts/route.ts`)
- Alert logic → Database pool: checks alert data (evidence: `src/lib/alerts.ts`)
- Alert polling → Alerts: polls and acknowledges (evidence: `src/hooks/useAlerts.ts`)
- Maintenance workflows → Database pool: stores requests (evidence: `src/app/api/maintenance/route.ts`)
- PDF and CSV reports → Reading queries: exports readings
- Admin management → Database pool: manages records (evidence: `src/app/api/admin/ponds/route.ts`)
- Admin management → Admin guard: checks permissions (evidence: `src/app/api/admin/ponds/route.ts`)
- Admin guard → Credentials authentication: checks admin role (evidence: `src/lib/admin.ts`)
- Credentials authentication → Database pool: loads credentials (evidence: `src/auth.ts`)
- Credentials authentication → Auth configuration: extends options (evidence: `src/auth.ts`)
- Login and session UI → Credentials authentication: signs in
- Application shell → Client auth state: uses session state (evidence: `src/components/MainLayout.tsx`)
- Application shell → Alert polling: uses alert polling (evidence: `src/components/MainLayout.tsx`)
- Utilization view → Utilization API: requests utilization
- Threshold settings → Threshold management: configures thresholds
- Notifications view → Maintenance workflows: handles maintenance
- Notifications view → Alerts: shows alerts
