FieldDB

Descripción general

FieldDB es una plataforma para recopilar y analizar datos ambientales hiperlocales procedentes de sensores. Recibe telemetría de estaciones meteorológicas y nodos de calidad del aire, almacena series temporales y muestra las mediciones tanto a los propietarios de los dispositivos como a los visitantes del mapa público.

A diferencia de los datos por satélite o los promedios de toda una ciudad, FieldDB trabaja con lecturas de dispositivos terrestres concretos. La plataforma combina el registro de equipos, una API de ingesta de datos, gráficos analíticos y la publicación controlada de estaciones.

Funciones del producto

El sistema ofrece:

• Registro de dispositivos y emisión de claves de API individuales
• Carga por lotes de mediciones meteorológicas y de calidad del aire
• Protección frente al registro duplicado de una misma medición
• Estados online, stale y offline para los dispositivos
• Gráficos y tablas para periodos desde una hora hasta 30 días
• Métricas de temperatura, humedad, presión, PM2.5, PM10, viento, lluvia y punto de rocío
• Un panel general con el número de dispositivos, la última sincronización y las alertas
• Un mapa público para las estaciones cuyos propietarios han autorizado su publicación
• Una interfaz en inglés, español, alemán y ruso

El mapa público nunca devuelve las coordenadas exactas de un dispositivo. Antes de publicarse, la ubicación se convierte en un geohash de precisión limitada y la API externa devuelve el centro de esa zona.

Arquitectura

FieldDB está construido como un monorepo e incluye:

• Una aplicación web con Next.js
• Una API con Hono y documentación OpenAPI
• PostgreSQL con la extensión TimescaleDB para series temporales
• Prisma para el esquema de datos y las migraciones
• Better Auth para las sesiones web
• Keycloak como proveedor OIDC
• Rutas BFF en la aplicación web para acceder a la API
• Google Maps para el mapa público de estaciones
• Un paquete compartido para el registro estructurado y las constantes de la aplicación

Las mediciones se almacenan en una hypertable de TimescaleDB. La API puede devolver tanto puntos sin procesar como datos agregados por intervalos de tiempo. La clave de un dispositivo se muestra al usuario una sola vez, mientras que la base de datos almacena únicamente su hash SHA-256.

Infraestructura y SRE

El proyecto cuenta con:

• GitLab CI con lint, comprobación de tipos, compilación, pruebas y auditoría de dependencias
• Construcción de contenedores con Kaniko
• Imágenes independientes para la aplicación web, la API, el migrador y el tema de Keycloak
• Comprobaciones de salud para la API y la aplicación web
• Comprobaciones de calidad del código con SonarQube
• Renovate para actualizar dependencias
• Registros JSON estructurados en producción
• Un entorno local con TimescaleDB y Keycloak mediante Testcontainers
• Despliegue GitOps con una tarea independiente para las migraciones de la base de datos
• Límites para la vida útil de la caché de compilación y limpieza de imágenes antiguas del registro

Las migraciones no se ejecutan junto con la API. Existe una imagen independiente diseñada para ejecutarse como un Job de Kubernetes antes de actualizar la aplicación. Esto reduce el riesgo de que varias instancias de la API intenten realizar la misma migración al mismo tiempo.

Retos de ingeniería

FieldDB reúne retos de telemetría de series temporales, autenticación y protección de la ubicación de los dispositivos:

• Ingesta idempotente de lotes de hasta 500 mediciones
• Almacenamiento y agregación de series temporales en TimescaleDB
• Emisión y almacenamiento seguros de claves de dispositivos
• Separación de los datos privados del propietario y la representación pública de la estación
• Reducción de la precisión de las coordenadas antes de publicar una ubicación en el mapa
• Gestión correcta de los callbacks de OAuth con rutas localizadas
• Inclusión de las claves de Google Maps durante la compilación y configuración de los referrers permitidos
• Obtención interna de sesiones web sin llamar al endpoint TLS público desde el mismo pod
• Ejecución de las migraciones antes de desplegar una nueva versión de la API

Como resultado, los propietarios obtienen mediciones detalladas de sus dispositivos, mientras que el público solo puede ver las estaciones publicadas expresamente y unas coordenadas geográficamente anonimizadas.