# normalsuperiordeldistritodebarranquilla/weather-station architecture

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

- Interactive diagram: https://gitdiagram.com/normalsuperiordeldistritodebarranquilla/weather-station
- Repository: https://github.com/normalsuperiordeldistritodebarranquilla/weather-station

## Overview

1. **What this repository is**
   - M1K1U is an IoT monitoring platform for a weather station.
   - It has three main runtime parts: an ESP32/Arduino telemetry source, a FastAPI backend, and a React frontend.
   - The backend stores telemetry locally in SQLite by default, with PostgreSQL supported through `DATABASE_URL`.

2. **Core system boundary**
   - The main architectural split is between **telemetry ingestion** and **user-facing visualization**.
   - The ESP32 pushes readings into the backend through a protected REST endpoint.
   - The frontend never talks to the device directly; it only consumes backend APIs.

3. **Backend structure**
   - The backend is organized in classic layers:
     - `routers` expose HTTP endpoints.
     - `services` contain business logic for auth, sensor data, alerts, seeding, and diagnostics.
     - `models` define persistence entities.
     - `schemas` define API contracts.
     - `core` holds config, security, and metric registry logic.
   - `main.py` is the application entrypoint and `database.py` manages the SQLAlchemy connection/session.

4. **Telemetry ingestion flow**
   - The ESP32 sends JSON readings to `POST /api/sensor-data`.
   - This endpoint requires `X-API-Key`, making device ingestion separate from human authentication.
   - Incoming payloads are normalized against the master metric contract, then persisted as sensor records.
   - If the timestamp is missing, the backend generates it; if it arrives without timezone, it is normalized to UTC.

5. **Telemetry read path**
   - The frontend reads from authenticated endpoints such as:
     - latest reading
     - historical series
     - station statistics
     - sensor detail views
     - current alerts
   - The public landing page uses a public endpoint that can return real data or an empty-state payload when no telemetry exists yet.
   - This creates a clean split between public marketing-style views and authenticated monitoring views.

6. **Authentication and session boundary**
   - User auth is handled with JWT stored in an HttpOnly cookie.
   - Login, logout, and session introspection are exposed through `/api/auth/*`.
   - Because the cookie is HttpOnly, the browser UI relies on backend session state rather than reading tokens directly.
   - The default admin user is auto-seeded, which is why the repo can start without manual user setup.

7. **Alerts and diagnostics**
   - Alert generation is a backend service that derives operational and environmental warnings from the latest telemetry plus recent history.
   - Alerts include station silence, extreme temperature, freezing risk, pressure drops, strong wind, rain detection, and sensor flatline/missing-field conditions.
   - A separate sensor diagnostics endpoint computes per-metric health/status, which supports the “detail by sensor” UI.

8. **Persistence and schema management**
   - SQLite is the default embedded datastore and lives inside the backend project tree.
   - PostgreSQL is supported for containerized deployment.
   - Alembic is used for schema evolution, with migrations already present for the initial schema and later metric additions.
   - The seed layer is intentionally small: it only creates the initial admin user, not sample telemetry.

9. **Frontend structure**
   - The frontend is a Vite + React + TypeScript app styled with Tailwind CSS.
   - It is organized around:
     - `pages` for top-level screens
     - `components` for reusable dashboard pieces
     - `services` for API calls
     - `hooks` for auth, alerts, and public landing state
     - `layouts` for authenticated shell structure
   - API calls use a shared HTTP client configured for cookie-based auth and the backend base URL.

10. **Frontend UX boundaries**
   - Public pages cover landing, about/project information, technologies, and general presentation.
   - Protected pages cover dashboard, console home, charts, history, live status, sensor detail, location, and alerts.
   - `ProtectedRoute` and `AuthRedirectRoute` enforce navigation rules based on session state.
   - The app shell components (`Navbar`, `Sidebar`, `Footer`, alert panels) frame the authenticated monitoring experience.

11. **Shared metric contract**
   - A key repo-specific design choice is the master metric contract aligned with `arduino.ino`.
   - The active fields are the same ones the backend and frontend understand: temperature, pressure, altitude, luminosity, rain analog/digital, and wind speed.
   - Backend metric registry logic and frontend metric configuration keep the UI and API aligned with the ESP32 payload format.
   - The aliases in the backend show that the system tolerates alternate field names from the device while normalizing to canonical keys.

12. **Deployment model**
   - The project supports local development with separate frontend and backend processes.
   - Docker Compose can bring up PostgreSQL plus the FastAPI backend together.
   - CORS and `VITE_API_URL` are important integration boundaries because the frontend and backend are intentionally decoupled services even in local dev.

Main entry points: [`backend/app/main.py`](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/main.py) (App entry), [`frontend/src/App.tsx`](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/App.tsx) (Routes), [`frontend/src/services/http.ts`](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/http.ts) (HTTP client), [`backend/app/services/sensor_data_service.py`](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/sensor_data_service.py) (Telemetry service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["ESP32 device"]
  node_arduino["Arduino sketch<br/>esp32 telemetry<br/>[arduino.ino]"]
end

subgraph group_backend["FastAPI backend"]
  node_backend_main["App entry<br/>api bootstrap<br/>[main.py]"]
  node_backend_config["Config<br/>settings<br/>[config.py]"]
  node_backend_security["Security<br/>jwt/cookie auth<br/>[security.py]"]
  node_backend_metrics["Metric registry<br/>contract map<br/>[metrics.py]"]
  node_backend_db[("Database<br/>sqlalchemy session<br/>[database.py]")]
  node_backend_models["Models"]
  node_backend_schemas["Schemas<br/>api contracts"]
  node_backend_router_auth["Auth router<br/>http endpoints<br/>[auth.py]"]
  node_backend_router_sensor["Sensor router<br/>ingestion api<br/>[sensor_data.py]"]
  node_backend_router_alerts["Alerts router<br/>monitoring api<br/>[alerts.py]"]
  node_backend_router_sensors["Sensors router<br/>detail api<br/>[sensors.py]"]
  node_backend_service_auth["Auth service<br/>session logic<br/>[auth_service.py]"]
  node_backend_service_sensor["Telemetry service<br/>ingestion logic"]
  node_backend_service_alerts["Alert service<br/>rules engine<br/>[alerts_service.py]"]
  node_backend_service_diag["Diagnostics<br/>health analysis"]
  node_backend_seed["Seed service<br/>bootstrap data<br/>[seed_service.py]"]
end

subgraph group_frontend["React frontend"]
  node_frontend_main["React entry<br/>ui bootstrap<br/>[main.tsx]"]
  node_frontend_app["Routes<br/>ui shell<br/>[App.tsx]"]
  node_frontend_http["HTTP client<br/>api client<br/>[http.ts]"]
  node_frontend_auth_service["Auth API<br/>frontend service<br/>[authService.ts]"]
  node_frontend_sensor_service["Sensor API<br/>frontend service"]
  node_frontend_alerts_service["Alerts API<br/>frontend service<br/>[alertsService.ts]"]
  node_frontend_auth_hook["Auth hook<br/>session state<br/>[useAuth.tsx]"]
  node_frontend_public_hook["Landing hook<br/>public state"]
  node_frontend_alerts_hook["Alerts hook<br/>ui state<br/>[useAlerts.ts]"]
  node_frontend_layout["App shell<br/>authenticated layout<br/>[AppShell.tsx]"]
  node_frontend_routes_auth["Protected route<br/>route guard<br/>[ProtectedRoute.tsx]"]
  node_frontend_routes_redirect["Auth redirect<br/>route guard"]
  node_frontend_page_public["Public pages<br/>landing/content<br/>[HomePage.tsx]"]
  node_frontend_page_auth["Auth pages<br/>login/session<br/>[LoginPage.tsx]"]
  node_frontend_page_dashboard["Dashboard pages<br/>monitoring views<br/>[DashboardPage.tsx]"]
end

subgraph group_deploy["Deployment"]
  node_deploy_compose["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_deploy_scripts["Start/stop scripts<br/>ops scripts<br/>[start_m1k1u.ps1]"]
end

node_arduino -->|"POST readings"| node_backend_router_sensor
node_arduino -->|"metric contract"| node_backend_metrics
node_backend_main -->|"loads config"| node_backend_config
node_backend_main -->|"initializes db"| node_backend_db
node_backend_main -->|"mounts"| node_backend_router_auth
node_backend_main -->|"mounts"| node_backend_router_sensor
node_backend_main -->|"mounts"| node_backend_router_alerts
node_backend_main -->|"mounts"| node_backend_router_sensors
node_backend_main -->|"seeds admin"| node_backend_seed
node_backend_router_auth -->|"uses"| node_backend_service_auth
node_backend_router_sensor -->|"api key"| node_backend_security
node_backend_router_sensor -->|"uses"| node_backend_service_sensor
node_backend_router_alerts -->|"uses"| node_backend_service_alerts
node_backend_router_sensors -->|"reads telemetry"| node_backend_service_sensor
node_backend_router_sensors -->|"computes health"| node_backend_service_diag
node_backend_service_auth -->|"signs sessions"| node_backend_security
node_backend_service_sensor -->|"normalizes fields"| node_backend_metrics
node_backend_service_sensor -->|"persists"| node_backend_models
node_backend_service_sensor -->|"writes/queries"| node_backend_db
node_backend_service_alerts -->|"reads history"| node_backend_db
node_backend_service_diag -->|"queries status"| node_backend_db
node_backend_service_auth -->|"users"| node_backend_models
node_backend_models -->|"serialized as"| node_backend_schemas
node_frontend_main -->|"renders"| node_frontend_app
node_frontend_app -->|"guards"| node_frontend_routes_auth
node_frontend_app -->|"guards"| node_frontend_routes_redirect
node_frontend_app -->|"wraps"| node_frontend_layout
node_frontend_app -->|"public screens"| node_frontend_page_public
node_frontend_app -->|"auth screens"| node_frontend_page_auth
node_frontend_app -->|"monitoring screens"| node_frontend_page_dashboard
node_frontend_http -->|"session calls"| node_backend_router_auth
node_frontend_http -->|"telemetry reads"| node_backend_router_sensors
node_frontend_http -->|"alert reads"| node_backend_router_alerts
node_frontend_auth_service -->|"uses"| node_frontend_http
node_frontend_sensor_service -->|"uses"| node_frontend_http
node_frontend_alerts_service -->|"uses"| node_frontend_http
node_frontend_auth_hook -->|"drives"| node_frontend_auth_service
node_frontend_public_hook -->|"reads public data"| node_frontend_sensor_service
node_frontend_alerts_hook -->|"reads alerts"| node_frontend_alerts_service
node_frontend_page_public -->|"state"| node_frontend_public_hook
node_frontend_page_auth -->|"session state"| node_frontend_auth_hook
node_frontend_page_dashboard -->|"alert state"| node_frontend_alerts_hook
node_frontend_page_dashboard -->|"telemetry views"| node_frontend_sensor_service
node_deploy_compose -->|"runs backend"| node_backend_main
node_deploy_compose -->|"postgres"| node_backend_db
node_deploy_scripts -->|"start/stop"| node_backend_main
node_deploy_scripts -->|"start/stop"| node_frontend_main

click node_arduino "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/arduino.ino"
click node_backend_main "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/config.py"
click node_backend_security "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/security.py"
click node_backend_metrics "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/metrics.py"
click node_backend_db "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/database.py"
click node_backend_models "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/tree/main/backend/app/models"
click node_backend_schemas "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/tree/main/backend/app/schemas"
click node_backend_router_auth "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/auth.py"
click node_backend_router_sensor "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/sensor_data.py"
click node_backend_router_alerts "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/alerts.py"
click node_backend_router_sensors "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/sensors.py"
click node_backend_service_auth "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/auth_service.py"
click node_backend_service_sensor "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/sensor_data_service.py"
click node_backend_service_alerts "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/alerts_service.py"
click node_backend_service_diag "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/sensor_diagnostics_service.py"
click node_backend_seed "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/seed_service.py"
click node_frontend_main "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/main.tsx"
click node_frontend_app "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/App.tsx"
click node_frontend_http "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/http.ts"
click node_frontend_auth_service "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/authService.ts"
click node_frontend_sensor_service "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/sensorDataService.ts"
click node_frontend_alerts_service "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/alertsService.ts"
click node_frontend_auth_hook "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/useAuth.tsx"
click node_frontend_public_hook "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/usePublicLanding.ts"
click node_frontend_alerts_hook "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/useAlerts.ts"
click node_frontend_layout "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/layouts/AppShell.tsx"
click node_frontend_routes_auth "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/components/ProtectedRoute.tsx"
click node_frontend_routes_redirect "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/components/AuthRedirectRoute.tsx"
click node_frontend_page_public "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/HomePage.tsx"
click node_frontend_page_auth "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/LoginPage.tsx"
click node_frontend_page_dashboard "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_deploy_compose "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/docker-compose.yml"
click node_deploy_scripts "https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/scripts/start_m1k1u.ps1"

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_arduino toneBlue
class node_backend_main,node_backend_config,node_backend_security,node_backend_metrics,node_backend_db,node_backend_models,node_backend_schemas,node_backend_router_auth,node_backend_router_sensor,node_backend_router_alerts,node_backend_router_sensors,node_backend_service_auth,node_backend_service_sensor,node_backend_service_alerts,node_backend_service_diag,node_backend_seed toneAmber
class node_frontend_main,node_frontend_app,node_frontend_http,node_frontend_auth_service,node_frontend_sensor_service,node_frontend_alerts_service,node_frontend_auth_hook,node_frontend_public_hook,node_frontend_alerts_hook,node_frontend_layout,node_frontend_routes_auth,node_frontend_routes_redirect,node_frontend_page_public,node_frontend_page_auth,node_frontend_page_dashboard toneMint
class node_deploy_compose,node_deploy_scripts toneRose
```

## Components

### ESP32 device

Telemetry source and shared metric contract

- [Arduino sketch](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/arduino.ino): esp32 telemetry · ESP32 weather-station firmware and master metric contract · `arduino.ino`

### FastAPI backend

Ingestion, auth, persistence, and alerting

- [App entry](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/main.py): api bootstrap · FastAPI application setup and router wiring · `backend/app/main.py`
- [Config](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/config.py): settings · Environment, CORS, and database/runtime configuration · `backend/app/core/config.py`
- [Security](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/security.py): jwt/cookie auth · API key and JWT cookie security helpers · `backend/app/core/security.py`
- [Metric registry](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/core/metrics.py): contract map · Canonical sensor fields and alias normalization · `backend/app/core/metrics.py`
- [Database](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/database.py): sqlalchemy session · Engine and session management for SQLite or PostgreSQL · `backend/app/database.py`
- [Models](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/tree/main/backend/app/models): persistence models · User and sensor-data entities · `backend/app/models`
- [Schemas](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/tree/main/backend/app/schemas): api contracts · Request and response shapes for auth, telemetry, alerts, and sensor detail · `backend/app/schemas`
- [Auth router](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/auth.py): http endpoints · Login, logout, and session introspection endpoints · `backend/app/routers/auth.py`
- [Sensor router](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/sensor_data.py): ingestion api · Protected telemetry ingestion endpoint for the device · `backend/app/routers/sensor_data.py`
- [Alerts router](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/alerts.py): monitoring api · Current alerts and alert-derived views · `backend/app/routers/alerts.py`
- [Sensors router](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/routers/sensors.py): detail api · Latest, history, statistics, and sensor-detail endpoints · `backend/app/routers/sensors.py`
- [Auth service](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/auth_service.py): session logic · User authentication and JWT session handling · `backend/app/services/auth_service.py`
- [Telemetry service](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/sensor_data_service.py): ingestion logic · Normalize, validate, and persist incoming readings · `backend/app/services/sensor_data_service.py`
- [Alert service](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/alerts_service.py): rules engine · Derive operational and environmental warnings from telemetry · `backend/app/services/alerts_service.py`
- [Diagnostics](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/sensor_diagnostics_service.py): health analysis · Per-sensor health and status computation · `backend/app/services/sensor_diagnostics_service.py`
- [Seed service](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/backend/app/services/seed_service.py): bootstrap data · Creates the initial admin user · `backend/app/services/seed_service.py`

### React frontend

Public site and authenticated monitoring UI

- [React entry](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/main.tsx): ui bootstrap · Vite/React application entrypoint · `frontend/src/main.tsx`
- [Routes](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/App.tsx): ui shell · Top-level route map and page composition · `frontend/src/App.tsx`
- [HTTP client](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/http.ts): api client · Shared backend client with cookie-based auth and base URL · `frontend/src/services/http.ts`
- [Auth API](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/authService.ts): frontend service · Login and session calls · `frontend/src/services/authService.ts`
- [Sensor API](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/sensorDataService.ts): frontend service · Telemetry, history, and sensor-detail calls · `frontend/src/services/sensorDataService.ts`
- [Alerts API](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/services/alertsService.ts): frontend service · Alert-fetching calls · `frontend/src/services/alertsService.ts`
- [Auth hook](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/useAuth.tsx): session state · Browser session state and auth flow · `frontend/src/hooks/useAuth.tsx`
- [Landing hook](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/usePublicLanding.ts): public state · Public landing-page data and empty-state handling · `frontend/src/hooks/usePublicLanding.ts`
- [Alerts hook](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/hooks/useAlerts.ts): ui state · Alert state for dashboard panels · `frontend/src/hooks/useAlerts.ts`
- [App shell](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/layouts/AppShell.tsx): authenticated layout · Navbar, sidebar, footer, and monitoring shell · `frontend/src/layouts/AppShell.tsx`
- [Protected route](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/components/ProtectedRoute.tsx): route guard · Blocks unauthenticated monitoring pages · `frontend/src/components/ProtectedRoute.tsx`
- [Auth redirect](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/components/AuthRedirectRoute.tsx): route guard · Redirects logged-in users away from auth pages · `frontend/src/components/AuthRedirectRoute.tsx`
- [Public pages](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/HomePage.tsx): landing/content · Home, about, project info, and technologies pages · `frontend/src/pages/HomePage.tsx`
- [Auth pages](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/LoginPage.tsx): login/session · Login and session-aware entry pages · `frontend/src/pages/LoginPage.tsx`
- [Dashboard pages](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/frontend/src/pages/DashboardPage.tsx): monitoring views · Dashboard, console, charts, history, live status, location, alerts, and sensor detail · `frontend/src/pages/DashboardPage.tsx`

### Deployment

Local and container startup

- [Compose stack](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/docker-compose.yml): deployment · Runs backend with PostgreSQL for containerized deployment · `docker-compose.yml`
- [Start/stop scripts](https://github.com/normalsuperiordeldistritodebarranquilla/weather-station/blob/main/scripts/start_m1k1u.ps1): ops scripts · Local process orchestration helpers · `scripts/start_m1k1u.ps1`

## Connections

- Arduino sketch → Sensor router: POST readings · ESP32 sends telemetry JSON to the protected ingestion endpoint
- Arduino sketch → Metric registry: metric contract · Firmware and backend share canonical sensor fields and aliases
- App entry → Config: loads config · Application bootstrap reads runtime settings
- App entry → Database: initializes db · Startup wires SQLAlchemy session and engine
- App entry → Auth router: mounts · Registers auth endpoints
- App entry → Sensor router: mounts · Registers telemetry ingestion endpoints
- App entry → Alerts router: mounts · Registers alert endpoints
- App entry → Sensors router: mounts · Registers sensor read endpoints
- App entry → Seed service: seeds admin · Bootstraps the default admin user
- Auth router → Auth service: uses · Auth endpoints delegate to auth business logic
- Sensor router → Security: api key · Ingestion requires X-API-Key protection
- Sensor router → Telemetry service: uses · Telemetry endpoint delegates normalization and persistence
- Alerts router → Alert service: uses · Alert views are derived by alert service
- Sensors router → Telemetry service: reads telemetry · Read endpoints query latest, history, and statistics
- Sensors router → Diagnostics: computes health · Sensor detail views include per-metric diagnostics
- Auth service → Security: signs sessions · Auth service issues and verifies JWT cookie sessions
- Telemetry service → Metric registry: normalizes fields · Telemetry is mapped to the master metric contract
- Telemetry service → Models: persists · Normalized readings are stored as sensor records
- Telemetry service → Database: writes/queries · Uses the database session for telemetry storage
- Alert service → Database: reads history · Alert rules inspect recent telemetry and latest readings
- Diagnostics → Database: queries status · Diagnostics compute per-sensor health from stored data
- Auth service → Models: users · User records back authentication
- Models → Schemas: serialized as · Models are exposed through API contracts
- React entry → Routes: renders · Bootstraps the application route tree
- Routes → Protected route: guards · Protects authenticated monitoring pages
- Routes → Auth redirect: guards · Redirects signed-in users away from auth pages
- Routes → App shell: wraps · Authenticated views use the shared shell
- Routes → Public pages: public screens · Home and informational pages
- Routes → Auth pages: auth screens · Login and session-related pages
- Routes → Dashboard pages: monitoring screens · Dashboard and operational views
- HTTP client → Auth router: session calls · Frontend auth requests target backend auth endpoints
- HTTP client → Sensors router: telemetry reads · Dashboard pages consume backend sensor APIs
- HTTP client → Alerts router: alert reads · Alert panels consume backend alert APIs
- Auth API → HTTP client: uses · Auth API is built on the shared HTTP client
- Sensor API → HTTP client: uses · Sensor data API is built on the shared HTTP client
- Alerts API → HTTP client: uses · Alerts API is built on the shared HTTP client
- Auth hook → Auth API: drives · Browser session state is managed through auth API calls
- Landing hook → Sensor API: reads public data · Landing content can show real telemetry or empty state
- Alerts hook → Alerts API: reads alerts · Dashboard alert state comes from the alerts API
- Public pages → Landing hook: state · Public pages use landing data hook
- Auth pages → Auth hook: session state · Auth pages rely on browser session state
- Dashboard pages → Alerts hook: alert state · Monitoring pages surface live alerts
- Dashboard pages → Sensor API: telemetry views · Charts, history, status, and sensor detail use telemetry APIs
- Compose stack → App entry: runs backend · Container deployment launches the FastAPI service
- Compose stack → Database: postgres · Compose provides the PostgreSQL-backed persistence option
- Start/stop scripts → App entry: start/stop · Local scripts manage backend runtime lifecycle
- Start/stop scripts → React entry: start/stop · Local scripts manage frontend runtime lifecycle
