epaper-display/LORAWEB_NEU/docs/superpowers/specs/2026-03-19-loraweb-design.md

LoRaWAN Web Portal – Design Specification

Date: 2026-03-19 Based on: Pflichtenheft v2.2 (März 2026) Approach: Bottom-up implementation, pflichtenheft as goal with flexibility in implementation details

---

1. Overview

Web-based monitoring portal for LoRaWAN sensor infrastructure. Receives uplink data from IoT devices via ChirpStack HTTP Integration, stores measurements in InfluxDB, manages device/sensor configuration in SQLite, and presents everything through a secured React frontend.

Key Decisions (Deviations from Pflichtenheft)

Area	Pflichtenheft	Implementation	Reason
SQLx	0.7	0.8	Current version, better SQLite support
Axum	0.7	0.8	Current version, improved API
Vite	5	6	Faster builds, no breaking changes for us
Tailwind	3.4	4	CSS-based engine, better performance
Rust Edition	2021	2024	Current standard
Deploy path	—	/opt/loraweb	As specified in pflichtenheft

React 18, config crate, and core architecture remain unchanged.

---

2. Project Structure

LORAWEB_NEU/
├── Cargo.toml                    # Workspace root (members: backend/daemon, backend/api)
├── backend/
│   ├── daemon/
│   │   ├── Cargo.toml
│   │   ├── Dockerfile
│   │   └── src/
│   │       ├── main.rs           # Tokio runtime, task spawning
│   │       ├── config.rs         # AppConfig via config crate
│   │       ├── http.rs           # Axum HTTP ingest listener
│   │       ├── influx.rs         # InfluxDB writer
│   │       ├── db.rs             # Topic registration (SQLite)
│   │       └── alarm.rs          # Alarm monitor loop
│   └── api/
│       ├── Cargo.toml
│       ├── Dockerfile
│       └── src/
│           ├── main.rs           # Router, DB init, AppState
│           ├── auth.rs           # JWT, Argon2, TOTP
│           ├── sensors.rs        # CRUD + data + display-config
│           ├── topics.rs         # Topic management
│           ├── alarms.rs         # Alarm endpoints
│           └── users.rs          # User CRUD + 2FA
├── frontend/
│   ├── src/
│   │   ├── App.tsx               # Router, protected routes
│   │   ├── api/client.ts         # Axios instance + API functions
│   │   ├── store/authStore.ts    # React Context auth state
│   │   ├── pages/
│   │   │   ├── LoginPage.tsx
│   │   │   ├── DashboardPage.tsx
│   │   │   ├── SensorsPage.tsx   # DataModal, multi-chart, mobile cards
│   │   │   ├── UnknownTopicsPage.tsx
│   │   │   ├── AlarmsPage.tsx
│   │   │   └── UsersPage.tsx
│   │   └── components/
│   │       ├── Layout.tsx        # Responsive sidebar + hamburger drawer
│   │       └── StatusBadge.tsx
│   ├── Dockerfile
│   └── nginx.conf
├── database/
│   └── migrations/001_initial.sql
├── deploy/
│   ├── docker-compose.yml        # Project name: loraweb
│   ├── .env.example
│   └── loraweb.service           # systemd unit
└── docs/

---

3. Database Schema (SQLite)

Three tables, created idempotently (CREATE TABLE IF NOT EXISTS) at startup by both daemon and API.

topics

Represents a physical LoRaWAN device identified by DevEUI.

Column	Type	Description
id	TEXT (UUID v4)	Primary key
topic	TEXT UNIQUE	DevEUI
approved	INTEGER (0/1)	0 = unknown, 1 = approved
last_seen	TEXT (RFC3339)	Last uplink timestamp
alarm_status	TEXT	active / warning / alarm / unknown
alarm_threshold_hours	REAL	Per-device threshold (0 = use global)
created_at	TEXT (RFC3339)	First registration

sensors

Logical sensor entity assigned to a topic.

Column	Type	Description
id	TEXT (UUID v4)	Primary key
name	TEXT	Display name
description	TEXT	Optional description
location	TEXT	Location string
sensor_type	TEXT	Type (e.g. "Temperatur")
active	INTEGER (0/1)	Active flag
topic_id	TEXT FK → topics.id	Assigned topic (nullable)
display_config	TEXT (JSON)	Per-sensor field config
created_at	TEXT (RFC3339)	Creation date

users

Column	Type	Description
id	INTEGER PK AUTOINCREMENT	Primary key
username	TEXT UNIQUE	Username
password_hash	TEXT	Argon2id hash
role	TEXT	"user" or "admin"
totp_secret	TEXT	Base32 TOTP secret (nullable)
totp_enabled	INTEGER (0/1)	2FA active
created_at	TEXT (RFC3339)	Creation date

---

4. Daemon Design

Single Rust binary running two async tasks via Tokio:

4.1 HTTP Ingest (Axum, Port 8080)

• POST /?event=up: Parse ChirpStack JSON → register unknown DevEUI in topics (approved=0) → write all object fields + RF metadata (rssi, snr, dr, f_cnt, f_port) to InfluxDB measurement sensor_data
• Tags: dev_eui, device_name, application_name
• Timestamp from ChirpStack time field
• Other events (join, ack, txack, log, status): return 200 OK, no processing
• InfluxDB errors: log and continue, no crash

4.2 Alarm Monitor (Tokio interval loop)

• Runs every check_interval_secs (default 60)
• Queries all topics with approved=1
• Per topic: use alarm_threshold_hours if > 0, otherwise global threshold
• Status logic:
  • last_seen is NULL → unknown
  • hours since last seen < warning threshold → active
  • hours since last seen < alarm threshold → warning
  • hours since last seen >= alarm threshold → alarm
• Updates alarm_status in SQLite

4.3 Configuration

Via config crate: loads daemon-config.toml + environment variables (prefix LORAWEB__).

Key	Default	Description
http.bind	0.0.0.0	Bind address
http.port	8080	HTTP port
influx.url	http://localhost:8086	InfluxDB URL
influx.token	—	API token
influx.org	loraweb	Organization
influx.bucket	sensors	Bucket
database.path	loraweb.db	SQLite path
alarm.warning_threshold_hours	2.0	Warning threshold
alarm.alarm_threshold_hours	6.0	Alarm threshold
alarm.check_interval_secs	60	Check interval

4.4 Startup

Log banner showing ingest URL and ChirpStack configuration hint.

---

5. REST API Design

Axum on port 3001, shared SQLite DB with daemon.

5.1 Authentication

• POST /api/auth/login: Verify username/password (Argon2id)
  • If TOTP enabled: return { totp_required: true }
  • Second request with TOTP code → issue JWT
  • If no TOTP: issue JWT directly
• JWT: HS256, 24h validity, contains user id + role
• Auth middleware extracts Bearer token, injects user info
• Default admin created at first startup (password from env var)

5.2 Endpoints

Route	Method	Auth	Description
/api/auth/login	POST	No	Login (+ optional TOTP)
/api/sensors	GET	Yes	List all sensors
/api/sensors	POST	Yes	Create sensor
/api/sensors/:id	GET	Yes	Sensor detail
/api/sensors/:id	PUT	Yes	Update sensor
/api/sensors/:id	DELETE	Yes	Delete sensor (resets topic to unapproved)
/api/sensors/:id/data	GET	Yes	InfluxDB proxy, ?hours=N
/api/sensors/:id/display-config	GET	Yes	Get field config
/api/sensors/:id/display-config	PUT	Yes	Save field config
/api/topics	GET	Yes	List all topics
/api/topics/:id	PUT	Yes	Approve, assign, update
/api/topics/:id/threshold	PUT	Yes	Set alarm threshold
/api/alarms	GET	Yes	Alarm summary
/api/users	GET	Admin	List users
/api/users	POST	Admin	Create user
/api/users/:id	PUT	Admin	Update user
/api/users/:id	DELETE	Admin	Delete user
/api/users/:id/totp	POST	Admin	Enable 2FA (returns secret + QR URI)
/api/users/:id/totp	DELETE	Admin	Disable 2FA

5.3 InfluxDB Proxy

• Sends Flux query to InfluxDB via reqwest
• Receives annotated CSV (after pivot)
• Parses CSV to JSON array server-side
• Returns JSON to frontend — no InfluxDB credentials exposed

---

6. Frontend Design

React 18 + TypeScript, Vite 6, Tailwind 4, Recharts.

6.1 Pages

1. LoginPage: Username/password form, conditional TOTP input step
2. DashboardPage: 4 status tiles (active/warning/alarm/unknown counts) + active alarm list
3. SensorsPage: Table (desktop) / cards (mobile), CRUD modals, DataModal with two tabs:
   • "Diagramme": Charts per configured panels (D1-D8), time selector, RF metadata toggle
   • "Einrichten": Per-field config (label, unit, chart type, panel assignment)
4. UnknownTopicsPage: List of unapproved topics, dropdown to assign to free sensors
5. AlarmsPage: Active alarms and warnings list
6. UsersPage (admin only): User CRUD, 2FA enable/disable

6.2 Charts (Recharts)

• Line chart: Time series, connectNulls enabled
• Bar chart (daily): Frontend aggregates raw data by date
• Bar chart (weekly): Frontend aggregates by calendar week
• Pie chart: Percentage distribution
• Fields assigned to panels D1-D8; same panel number = same chart
• RF metadata (RSSI, SNR, DR) toggleable in line charts
• Time ranges: 1h, 6h, 24h, 7d, 30d, 90d
• Data table below charts: last 20 values with configured labels/units

6.3 Responsive Layout

• Desktop (lg: breakpoint, 1024px+): Static sidebar navigation
• Mobile: Top bar with hamburger icon → animated slide-in drawer
• Tables switch to card lists on mobile (hidden sm:block / sm:hidden)
• DataModal: Centered overlay on desktop, bottom-sheet on mobile

6.4 Auth & State

• React Context API for auth state
• localStorage: loraweb_token, loraweb_user
• Axios interceptor: 401 response → automatic logout + redirect to login
• All pages auto-refresh every 15 seconds

---

7. Infrastructure

7.1 Docker Compose

Project name: loraweb. Four services:

Service	Image	Ports (host)	Volumes
daemon	Custom (Rust)	8080	loraweb-data:/data
api	Custom (Rust)	— (internal)	loraweb-data:/data
frontend	Custom (nginx)	80	—
influxdb	influxdb:2.7	— (internal)	loraweb-influx:/var/lib/influxdb2

All containers run as user loraweb (UID 1001).

7.2 Dockerfiles

Rust (daemon + api): Multi-stage build

• Stage 1: rust:1.88-slim → cargo fetch → cargo build --release
• Stage 2: debian:bookworm-slim → copy binary, create non-root user
• Build context: project root (Cargo workspace)

Frontend: Multi-stage build

• Stage 1: node:20-alpine → npm install --legacy-peer-deps → npm run build
• Stage 2: nginx:alpine → copy dist + nginx.conf

7.3 nginx.conf

• location /api/ → proxy_pass http://api:3001/api/
• location / → serve static files, try_files $uri /index.html (SPA fallback)

7.4 systemd

deploy/loraweb.service:

• WorkingDirectory=/opt/loraweb
• ExecStart=/usr/bin/docker compose up
• ExecStop=/usr/bin/docker compose down
• Restart=always

7.5 Secrets

All via .env file (not in git). .env.example as template with:

• JWT_SECRET, ADMIN_PASSWORD
• INFLUX_TOKEN, INFLUX_ORG, INFLUX_BUCKET
• DOCKER_INFLUXDB_INIT_* for InfluxDB bootstrap

---

8. Implementation Order (Bottom-Up)

1. Database migrations (SQL file + programmatic init)
2. Daemon (HTTP ingest + alarm monitor)
3. REST API (auth, CRUD, InfluxDB proxy)
4. Frontend (pages, charts, responsive layout)
5. Docker & infrastructure (Dockerfiles, Compose, nginx, systemd)

Each layer is testable independently before the next is built.