Skip to main content

​
Welcome to Invernaderos API

The Invernaderos API is a production-ready IoT greenhouse monitoring system that enables real-time sensor data collection, storage, and analysis for agricultural operations. Built with modern technologies and designed for scalability, it provides a robust platform for monitoring environmental conditions across multiple greenhouses.

Quick Start

Get your API running in under 5 minutes with Docker Compose

Architecture

Understand the system design and data flow

API Reference

Explore REST endpoints and authentication

WebSocket

Real-time sensor data streaming

​
What is Invernaderos API?

Invernaderos API is a multi-tenant IoT platform that receives sensor data from greenhouse devices via MQTT, stores time-series data in TimescaleDB, caches recent readings in Redis for fast access, and broadcasts real-time updates to connected clients via WebSocket/STOMP.

​
Key Features

Multi-Tenant

Isolated Data by TenantComplete data isolation with UUID-based tenant identification. Each agricultural company gets their own secure data space.

MQTT Integration

Industry-Standard IoTBuilt on MQTT protocol with EMQX broker. Topics: GREENHOUSE/{tenantId} for multi-tenant routing.

Time-Series Database

Optimized for Sensor DataTimescaleDB with automatic compression, 2-year retention policy, and continuous aggregates for hourly/daily statistics.

Real-Time WebSocket

Instant UpdatesSTOMP over WebSocket pushes sensor readings to clients instantly. No polling required.

Redis Caching

Lightning FastLast 1000 messages cached in Redis Sorted Set. Response time in milliseconds for recent data queries.

JWT Authentication

Secure AccessBearer token authentication with role-based access control. Password reset via email.

​
Technology Stack

Spring Boot 3.5.7

Modern Java framework with Jakarta EE 10+

Kotlin 2.2.21

Concise, type-safe language with K2 compiler

Java 21 LTS

Latest LTS with virtual threads and pattern matching

TimescaleDB

PostgreSQL 16 + TimescaleDB for time-series

Redis 7

In-memory cache with Lettuce client

EMQX

Enterprise MQTT broker with WebSocket support

​
System Architecture Overview

​
Data Flow

1

Sensors Publish

Greenhouse IoT devices publish sensor readings to MQTT topic GREENHOUSE/{tenantId} every 5-10 seconds.
2

MQTT Listener

Spring Integration MQTT adapter receives messages and routes to GreenhouseDataListener.
3

Processing Pipeline

MqttMessageProcessor processes each message:
  • Parses JSON payload (22 fields: temperature, humidity, sectors, extractors)
  • Caches in Redis Sorted Set (last 1000 messages)
  • Transforms to 22 SensorReading entities (one per field)
  • Batch inserts to TimescaleDB
  • Publishes Spring ApplicationEvent
4

WebSocket Broadcast

GreenhouseWebSocketHandler listens to event and broadcasts RealDataDto to all connected clients on /topic/greenhouse/messages.
5

Clients Receive

Mobile/web apps receive real-time updates via WebSocket. Historical data queried via REST API.

​
Real-World Sensor Data

The system handles real greenhouse sensor data with 22 fields per message: 
{
  "TEMPERATURA INVERNADERO 01": 24.5,
  "HUMEDAD INVERNADERO 01": 65.3,
  "TEMPERATURA INVERNADERO 02": 23.8,
  "HUMEDAD INVERNADERO 02": 68.2,
  "TEMPERATURA INVERNADERO 03": 25.1,
  "HUMEDAD INVERNADERO 03": 64.7,
  "INVERNADERO_01_SECTOR_01": 1.0,
  "INVERNADERO_01_SECTOR_02": 0.0,
  "INVERNADERO_01_SECTOR_03": 1.0,
  "INVERNADERO_01_SECTOR_04": 0.0,
  "INVERNADERO_02_SECTOR_01": 1.0,
  "INVERNADERO_02_SECTOR_02": 1.0,
  "INVERNADERO_02_SECTOR_03": 0.0,
  "INVERNADERO_02_SECTOR_04": 1.0,
  "INVERNADERO_03_SECTOR_01": 0.0,
  "INVERNADERO_03_SECTOR_02": 1.0,
  "INVERNADERO_03_SECTOR_03": 1.0,
  "INVERNADERO_03_SECTOR_04": 0.0,
  "INVERNADERO_01_EXTRACTOR": 850.5,
  "INVERNADERO_02_EXTRACTOR": 920.3,
  "INVERNADERO_03_EXTRACTOR": 780.2,
  "RESERVA": 0.0
}
Data Transformation: One JSON payload (22 fields) → 22 database rows. Each numeric field becomes a separate SensorReading entity for normalized time-series queries.

​
Multi-Tenant Architecture

The system supports complete tenant isolation with UUID-based tenant IDs:

​
MQTT Topic Structure

  • Legacy Format (backward compatible): GREENHOUSE → maps to tenantId = "DEFAULT"
  • Multi-Tenant Format: GREENHOUSE/{tenantId}
    • GREENHOUSE/SARA → tenantId = “SARA” (Vivero Sara)
    • GREENHOUSE/001 → tenantId = “001”
    • GREENHOUSE/NARANJOS → tenantId = “NARANJOS” (Los Naranjos farm)

​
Database Isolation

All tables include tenant_id UUID for filtering:
  • PostgreSQL Metadata: tenants, greenhouses, sensors, actuators, users, alerts
  • TimescaleDB: sensor_readings with indexed tenant_id column
  • Redis Cache: Keys include tenant context: greenhouse:messages:{tenantId}
Important: Existing sensor data has NULL tenant_id and requires manual migration. See Migration Guide for steps to populate tenant associations.

​
Use Cases

Agricultural Companies

Monitor multiple greenhouses across different locations. Track temperature, humidity, and environmental factors in real-time.

Research Institutions

Collect long-term environmental data for agricultural research. Analyze trends and optimize growing conditions.

IoT Integrators

Build custom dashboards and mobile apps on top of the API. Connect various sensor types and actuators.

Smart Farming

Automate irrigation, ventilation, and climate control based on real-time sensor data and thresholds.

​
Production Features

Docker Ready

Multi-stage Dockerfile with optimized layers. Complete docker-compose.yaml for local development.

Kubernetes Deployment

Production K8s manifests with StatefulSets, PersistentVolumes, and health checks.

Health Monitoring

Spring Boot Actuator endpoints: /actuator/health, /actuator/metrics, /actuator/prometheus.

OpenAPI Documentation

Interactive Swagger UI at /swagger-ui.html with try-it-out functionality.

Database Migrations

Flyway-managed SQL migrations (V2-V11 executed). Versioned schema changes with checksum validation.

Connection Pooling

HikariCP pools: TimescaleDB (max 20), PostgreSQL (max 10), Redis Lettuce (max 100 connections).

​
Performance Characteristics

Throughput: Handles 1000+ messages/second with batch insertsLatency: Redis cache responses in 1-5ms, TimescaleDB queries in 10-50msStorage: TimescaleDB compression (7-day policy) reduces storage by ~90%Retention: 2-year data retention with automatic cleanupScaling: Horizontal scaling with multiple API instances behind load balancer

​
Next Steps

Quick Start

Deploy with Docker in 5 minutes

Architecture

Deep dive into system design

API Docs

Explore endpoints
Built with Spring Boot 3.5.7 • Kotlin 2.2.21 • Java 21 • TimescaleDB • Redis 7 • EMQX

Build docs developers (and LLMs) love

Get started for freeTalk to us