Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/surqo/llms.txt

Use this file to discover all available pages before exploring further.

En esta guía vas a clonar el repositorio, configurar el entorno, levantar el backend de FastAPI, enviar tu primera lectura de sensor simulada y ver el sistema de análisis IA en funcionamiento — todo desde cero, en menos de 15 minutos. No necesitas hardware físico para completar el quickstart; la guía incluye un simulador IoT en Python que replica el modelo climático de Córdoba, Colombia.
Prerrequisitos antes de comenzar:
  • Python 3.11+ y uv (gestor de paquetes de Astral — instalación 10–100× más rápida que pip)
  • Node.js 20+ (para el frontend)
  • Cuentas gratuitas en: Supabase, Upstash Redis, HiveMQ Cloud, Groq

​
Pasos

1

Clonar el repositorio

Clona el repositorio y entra al directorio del backend:
git clone https://github.com/ricardomb-tech/surqo.git
cd surqo/backend
2

Instalar dependencias con uv

Instala todas las dependencias del proyecto con un solo comando. uv sync lee pyproject.toml y crea el entorno virtual automáticamente:
uv sync
3

Configurar variables de entorno

Copia el archivo de ejemplo y completa tus credenciales:
cp .env.example .env
Las variables mínimas requeridas para levantar el backend son:
# LLM Provider — Groq es el proveedor primario (gratis hasta 14.400 req/día)
LLM_PROVIDER=groq
GROQ_API_KEY=gsk_...
GROQ_MODEL=llama-3.3-70b-versatile

# Supabase — base de datos y autenticación
SUPABASE_URL=https://<project>.supabase.co
SUPABASE_KEY=<service-role-key>
DATABASE_URL=postgresql+asyncpg://...

# Upstash Redis — cache y cooldown de alertas
REDIS_URL=rediss://...

# App
APP_ENV=development
CORS_ORIGINS=["http://localhost:3000"]
Puedes obtener cada credencial aquí: GROQ_API_KEY → console.groq.com · SUPABASE_URL + SUPABASE_KEY → Supabase Dashboard → Settings → API · REDIS_URL → console.upstash.com → Redis → Connect.
4

Levantar el backend

Inicia el servidor de desarrollo de FastAPI:
uv run fastapi dev app/main.py
El backend estará disponible en http://localhost:8000/docs con la documentación interactiva de Swagger. Puedes verificar que el servicio está sano con:
curl http://localhost:8000/health
Respuesta esperada:
{ "status": "ok", "db": "ok", "env": "development" }
5

Enviar tu primera lectura de sensor

Envía una lectura simulada de un nodo ESP32 al endpoint de sensores. Reemplaza <your-jwt-token> con un token JWT de Supabase Auth y <your-farm-uuid> con el UUID de una finca creada previamente en POST /api/v1/farms/:
curl -X POST http://localhost:8000/api/v1/sensors/reading \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{
    "device_id": "ESP32-TEST-001",
    "farm_id": "<your-farm-uuid>",
    "soil_moisture_pct": 45.2,
    "soil_temp_c": 28.1,
    "air_temp_c": 31.5,
    "air_humidity_pct": 68.3,
    "uv_index": 7.2,
    "battery_mv": 3820,
    "rssi_dbm": -62,
    "firmware_version": "1.0.0"
  }'
El backend calcula automáticamente el VPD (Déficit de Presión de Vapor) usando la ecuación de Magnus y persiste la lectura en PostgreSQL. Si la humedad de suelo cae por debajo del 25% o el VPD supera 1.6 kPa, se genera una alerta automática.
6

Levantar el frontend

Desde la raíz del proyecto, instala dependencias del frontend y crea el archivo de variables de entorno:
cd ../frontend
npm install
Crea el archivo .env.local con las siguientes variables:
# Crear .env.local con:
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_...
Luego inicia el servidor de desarrollo:
npm run dev
El frontend estará disponible en http://localhost:3000. Las rutas protegidas (/dashboard, /farms, /sensors, /analyze, /alerts) requieren autenticación con Supabase Auth.

​
Simular hardware IoT sin un ESP32 físico

Si no tienes un nodo físico disponible, el repositorio incluye un simulador IoT en Python que replica el modelo climático de Córdoba, Colombia (temperatura senoidal 22°C→34°C, humedad inversa, lluvia probabilística, UV solar).
El simulador puede enviar lecturas vía HTTP al API local o vía MQTT a HiveMQ Cloud, replicando exactamente el comportamiento de un nodo ESP32 en campo.
cd iot-simulator
pip install httpx paho-mqtt

# Modo HTTP — envía lecturas al API local cada 10 segundos
python simulator.py --mode http --interval 10 --farm-id <uuid>
Para simular vía MQTT hacia HiveMQ Cloud (igual que el firmware real del ESP32): 
python simulator.py --mode mqtt \
  --mqtt-host tu-cluster.hivemq.cloud \
  --mqtt-user surqo-user \
  --mqtt-pass tu_password \
  --farm-id <uuid> \
  --device-id ESP32-DEMO-001

​
Próximos pasos

Con el backend corriendo y las primeras lecturas almacenadas, puedes explorar el resto de la plataforma:

Construir el nodo ESP32

Lista de componentes (~$15 USD), conexiones GPIO, configuración de config.h y comandos PlatformIO para compilar y subir el firmware al hardware real.

API completa

Referencia de todos los endpoints REST: fincas, sensores, análisis IA, alertas, usuarios y KPIs. Incluye esquemas de request/response y códigos de error.

Arquitectura del sistema

Diagrama del flujo completo: ESP32 → MQTT → FastAPI → PostgreSQL → WebSocket → Next.js. Stack tecnológico, modelos de dominio y decisiones de diseño.

Build docs developers (and LLMs) love

Get started for freeTalk to us