Bloomverd Backend

AI-Powered Precision Agriculture for Africa

---

Overview

Bloomverd is a full-stack agritech backend that gives African farmers access to agronomist-level intelligence through their smartphones. It combines IoT sensor networks, computer vision disease and yield predictions, and LLM-driven farm health analysis into a single, unified API.

The system monitors farms autonomously — collecting telemetry, running AI health assessments every few hours, triggering irrigation or image capture automatically when conditions require it, and surfacing actionable alerts so farmers can intervene before losses occur.

See ai/docs/ for deeper technical and business documentation.

---

Key Features

• Automated AI Health Monitoring — scheduled pipeline collects IoT telemetry and asks an LLM to score soil, crop, disease risk, and weather stress; results stored and alerted automatically
• Agentic IoT Control — the LLM can autonomously trigger irrigation, image capture, and sensor activation based on field conditions
• Conversational AI Assistant — multi-turn chat with 5 farm tools (health, predictions, devices, details, IoT commands), streamed token by token to the client
• Disease & Yield Predictions — external computer vision service analyzes geotagged field photos and returns risk levels (LOW / MODERATE / HIGH)
• IoT Device Management — AWS IoT Core integration for provisioning sensors, weather stations, drones, irrigation controllers with full X.509 certificate lifecycle; each device stores optional GPS coordinates (lat/lon) used by the prediction pipeline
• Subscription Tiers — Free / Popular / Premium plans enforced server-side, paid via Paystack
• Real-time Streaming — Server-Sent Events (SSE) for live IoT events and AI chat token streams
• Cloud File Storage — Cloudflare R2 (S3-compatible) with presigned upload URLs and CDN delivery
• Multi-Channel Notifications — prediction alerts delivered via in-app SSE stream, email, and SMS (Twilio); each channel toggled per-farmer in settings

---

Architecture Overview

┌──────────────┐
│   Client App  │  (mobile / web)
└──────┬───────┘
       │ GraphQL (Apollo Server v5)
       │ REST (auth, IoT webhooks, SSE)
┌──────▼────────────────────────────────┐
│           NestJS Application           │
│  Auth · Farmer · Farm · Health         │
│  Predictions · Chat · Payment          │
│  Email · FarmData · Upload             │
│  Notifications · SMS                   │
└──────┬────────────────────────────────┘
       │ BullMQ Jobs
┌──────▼──────────────────────────────────────────┐
│                  Workers                         │
│  HealthConsumer  PredictionConsumer              │
│  ChatConsumer    EmailProcessor                  │
│  FarmDataConsumer                                │
└──────┬──────────────────────────────────────────┘
       │
┌──────▼──────────────────────────────────────────┐
│               Infrastructure                     │
│  PostgreSQL 17   Redis    DynamoDB               │
│  AWS IoT Core    Cloudflare R2                   │
│  Ollama / LLM    Prediction ML Service           │
│  Twilio (SMS)                                    │
└─────────────────────────────────────────────────┘

---

Prerequisites

---

Quick Start (Docker)

The fastest way to run the full stack locally:

# 1. Clone and enter the repo
git clone <repo-url>
cd bloomverd-backend

# 2. Copy environment template and fill in your secrets
cp .env.example .env

# 3. Start PostgreSQL + Redis + the application
docker-compose up -d

# 4. (Optional) Start a local Ollama LLM service
docker-compose -f docker-compose.ollama.yml up -d

The API will be available at http://localhost:4000/graphql.

---

Manual Local Setup

If you prefer to run the app directly (requires Postgres and Redis already running):

# 1. Install dependencies
npm install

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env with your values (see table below)

# 3. Start supporting services (skip if already running)
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:17
docker run -d -p 6379:6379 redis:latest

# 4. Run database migrations
npm run migration:run

# 5. Start in development mode (hot reload)
npm run start:dev

---

Environment Variables

Copy .env.example to .env and supply values for your environment.

Server

Database

Redis

Auth / JWT

Google OAuth

Cloudflare R2 (file storage)

AWS IoT Core

AWS DynamoDB (telemetry)

Email

SMS (Twilio)

All three are optional — if omitted, SMS notifications are silently skipped.

Ollama / LLM

Prediction Service

Paystack

---

Available Scripts

---

Database Migrations

The project uses TypeORM migrations. Migrations run automatically on application startup (migrationsRun: true). For manual control:

# Apply all pending migrations
npm run migration:run

# Generate a new migration after changing entities
npm run migration:generate --name=DescriptiveName

# Undo the last applied migration
npm run migration:revert

Migration files live in src/database/migrations/.

---

Infrastructure as Code

The iac/ directory contains a Terraform configuration that provisions the full AWS deployment stack:

Deploy

cd iac
terraform init
terraform apply \
  -var="public_key=$(cat ~/.ssh/id_rsa.pub)" \
  -var="env_file_content=$(cat ../.env)" \
  -var="github_repo=bloomverd/bloomverd-backend"

Terraform state is stored in S3 (bloomverd-bucket). Requires Terraform ≥ 1.6.0 and AWS CLI credentials with IoT Core, EC2, DynamoDB, Lambda, SSM, and IAM permissions.

---

Testing

# Unit tests
npm run test

# Unit tests (watch mode)
npm run test:watch

# Coverage report
npm run test:cov

# End-to-end tests
npm run test:e2e

---

Further Documentation