FieldDB

Überblick

FieldDB ist eine Plattform zur Erfassung und Analyse hyperlokaler Umweltdaten von Sensoren. Sie nimmt Telemetriedaten von Wetterstationen und Luftqualitätsmessgeräten auf, speichert Zeitreihen und stellt die Messwerte sowohl Gerätebesitzern als auch Besuchern der öffentlichen Karte zur Verfügung.

Im Unterschied zu Satellitendaten oder stadtweiten Durchschnittswerten arbeitet FieldDB mit Messungen konkreter Geräte am Boden. Die Plattform verbindet Geräteregistrierung, eine API zur Datenaufnahme, analytische Diagramme und die kontrollierte Veröffentlichung von Stationen.

Produktfunktionen

Das System bietet:

• Registrierung von Geräten und Ausgabe individueller API-Schlüssel
• Stapelweise Übertragung von Wetter- und Luftqualitätsmessungen
• Schutz vor doppelter Speicherung derselben Messung
• Gerätestatus online, veraltet und offline
• Diagramme und Tabellen für Zeiträume von einer Stunde bis zu 30 Tagen
• Messwerte für Temperatur, Luftfeuchtigkeit, Luftdruck, PM2.5, PM10, Wind, Niederschlag und Taupunkt
• Ein Übersichts-Dashboard mit Geräteanzahl, letzter Synchronisierung und Warnmeldungen
• Eine öffentliche Karte für Stationen, deren Besitzer der Veröffentlichung zugestimmt haben
• Eine Benutzeroberfläche auf Englisch, Spanisch, Deutsch und Russisch

Die öffentliche Karte gibt niemals die exakten Koordinaten eines Geräts zurück. Vor der Veröffentlichung wird der Standort in einen Geohash mit begrenzter Genauigkeit umgewandelt; die externe API liefert nur den Mittelpunkt dieses Bereichs.

Architektur

FieldDB ist als Monorepo aufgebaut und umfasst:

• Eine Webanwendung auf Basis von Next.js
• Eine Hono-API mit OpenAPI-Dokumentation
• PostgreSQL mit der TimescaleDB-Erweiterung für Zeitreihen
• Prisma für Datenschema und Migrationen
• Better Auth für Web-Sitzungen
• Keycloak als OIDC-Anbieter
• BFF-Routen in der Webanwendung für API-Zugriffe
• Google Maps für die öffentliche Stationskarte
• Ein gemeinsames Paket für strukturierte Protokollierung und Anwendungskonstanten

Die Messwerte werden in einer TimescaleDB-Hypertable gespeichert. Die API kann sowohl Rohdaten als auch nach Zeitintervallen aggregierte Werte ausgeben. Der Geräteschlüssel wird dem Nutzer nur einmal angezeigt; in der Datenbank wird ausschließlich sein SHA-256-Hash gespeichert.

Infrastruktur & SRE

Für das Projekt wurden umgesetzt:

• GitLab CI mit Linting, Typprüfungen, Builds, Tests und Abhängigkeits-Audits
• Container-Builds mit Kaniko
• Separate Images für Webanwendung, API, Migrator und Keycloak-Theme
• Health Checks für API und Webanwendung
• SonarQube-Prüfungen der Codequalität
• Renovate für Abhängigkeits-Updates
• Strukturierte JSON-Logs in der Produktionsumgebung
• Eine lokale Umgebung mit TimescaleDB und Keycloak über Testcontainers
• GitOps-Deployment mit einer separaten Aufgabe für Datenbankmigrationen
• Begrenzte Lebensdauer des Build-Caches und Bereinigung alter Registry-Images

Migrationen werden nicht gemeinsam mit der API gestartet. Dafür gibt es ein separates Image, das vor der Aktualisierung der Anwendung als Kubernetes Job ausgeführt wird. So sinkt das Risiko, dass mehrere API-Instanzen gleichzeitig dieselbe Migration starten.

Technische Herausforderungen

FieldDB verbindet Aufgaben aus Zeitreihen-Telemetrie, Authentifizierung und Schutz von Gerätestandorten:

• Idempotente Aufnahme von Stapeln mit bis zu 500 Messungen
• Speicherung und Aggregation von Zeitreihen in TimescaleDB
• Sichere Ausgabe und Speicherung von Geräteschlüsseln
• Trennung privater Besitzerdaten von der öffentlichen Darstellung einer Station
• Reduzierung der Koordinatengenauigkeit vor der Veröffentlichung auf der Karte
• Korrekte Verarbeitung von OAuth-Callbacks mit lokalisierten Routen
• Übergabe von Google-Maps-Schlüsseln beim Build und Konfiguration zulässiger Referrer
• Interner Abruf von Web-Sitzungen, ohne aus demselben Pod den öffentlichen TLS-Endpunkt aufzurufen
• Ausführung von Migrationen vor dem Deployment einer neuen API-Version

Dadurch erhalten Gerätebesitzer detaillierte Messwerte, während öffentlich nur ausdrücklich freigegebene Stationen und geografisch anonymisierte Koordinaten erscheinen.