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.

Surqo is a full-stack IoT + AI platform composed of a FastAPI backend, a Next.js 15 frontend, and an optional IoT simulator that stands in for physical ESP32 hardware. This guide walks you through running every layer locally — from cloning the repo to seeing live sensor data stream into your browser dashboard.

​
Prerequisites

Before starting, make sure you have the following installed and accounts ready:
  • Python 3.11+ — required by the backend
  • uv (Astral) — replaces pip/venv; 10–100× faster installs
  • Node.js 20+ — required by the Next.js frontend
  • Supabase account — free tier at supabase.com (PostgreSQL + Auth)
  • Upstash Redis account — free tier at console.upstash.com (cache + alert cooldowns)
  • Groq API key — free at console.groq.com (Llama 3.3 70B, 14,400 req/day)
  • HiveMQ Cloud account (optional) — free at console.hivemq.cloud for MQTT; leave HIVEMQ_HOST empty to skip

​
Backend Setup

The backend is a FastAPI application managed entirely by uv. It connects to Supabase PostgreSQL, Upstash Redis, and — optionally — HiveMQ Cloud for MQTT ingestion.
1

Clone the repository and enter the backend directory

git clone https://github.com/ricardomb-tech/surqo.git
cd surqo/backend
2

Install dependencies with uv

uv sync reads pyproject.toml and creates an isolated virtual environment in one shot — no pip install or python -m venv required.
uv sync
3

Copy the example environment file and fill in your credentials

cp .env.example .env
Open .env in your editor and populate at minimum SUPABASE_URL, SUPABASE_KEY, DATABASE_URL, REDIS_URL, and GROQ_API_KEY. See the Environment Variables reference for the full list and where to obtain each value.
4

Start the FastAPI development server

uv run fastapi dev app/main.py
# → API:        http://localhost:8000
# → Swagger UI: http://localhost:8000/docs  (development only)
The fastapi dev command enables hot-reload automatically. Swagger UI is disabled in production (APP_ENV=production) but fully available in local development.
5

Run the test suite and linter

uv run pytest tests/ -v --cov=app
uv run ruff check app/
The test suite uses SQLite in-memory fixtures — no real database connection needed to run tests. All 86+ tests should pass on a clean clone.

​
Frontend Setup

The frontend is a Next.js 15 application using the App Router, React Server Components, and @supabase/ssr for cookie-based auth.
1

Enter the frontend directory and install packages

cd ../frontend
npm install
2

Create the local environment file

Next.js reads public variables from .env.local. Create the file with the values below — replace the Supabase placeholders with your real project URL and anon key.
.env.local
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://tu-proyecto.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_...
3

Start the Next.js development server

npm run dev
# → http://localhost:3000
The frontend proxies all /api/v1/* calls to NEXT_PUBLIC_API_URL (your local FastAPI). Make sure the backend is running first.

​
IoT Simulator

When developing without physical ESP32 hardware, the bundled Python simulator generates realistic microclimate readings and pushes them to the backend over HTTP or MQTT. 
cd ../iot-simulator
pip install httpx paho-mqtt

# HTTP mode — simplest, no MQTT broker needed
python simulator.py --mode http \
  --interval 10 \
  --farm-id <your-farm-uuid>

# MQTT mode — full IoT stack via HiveMQ Cloud
python simulator.py --mode mqtt \
  --mqtt-host tu-cluster.hivemq.cloud \
  --mqtt-user surqo-user \
  --mqtt-pass tu_password \
  --farm-id <your-farm-uuid> \
  --device-id ESP32-DEMO-001
The simulator models the microclimate of Córdoba, Colombia — the target deployment region for Surqo hardware nodes. Its synthetic data engine generates:
  • Temperature — sinusoidal curve ranging 22 °C → 34 °C across a 24-hour period
  • Humidity — inverse relationship to temperature (peaks at night, drops at midday)
  • Rainfall — probabilistic events that temporarily spike humidity and soil moisture
  • Solar UV index — sun-arc model peaking around solar noon
This produces data distributions that closely match real-field conditions, making it suitable for testing alert thresholds, AI analysis prompts, and dashboard visualisations.
To skip MQTT entirely in local development, set HIVEMQ_HOST= (empty string) in your backend .env file. The FastAPI lifespan startup will detect the empty value and start without launching the MQTT consumer — every other feature continues to work normally via HTTP ingestion.

Build docs developers (and LLMs) love

Get started for freeTalk to us