Arandu Technical Specification

Current Specification

This page describes the Arandu system architecture, runtime, data model, analytical surface, and operational controls.

1) System Purpose and Scope

Arandu is a WhatsApp-first agricultural intelligence platform designed for smallholder workflows. The system converts satellite and weather signals into actionable agronomic recommendations delivered through conversational messaging.

Primary channel: WhatsApp.
Primary user interaction: short natural-language queries and numbered menus.
Primary output modes: concise text recommendations and optional zoning/heatmap media.

2) Runtime and Deployment Architecture

Language/runtime: Python (FastAPI).
Web framework: FastAPI.
Hosting: Google Cloud Run (stateless container deployment).
Asynchronous processing: Cloud Tasks for heavy processing paths.

2.1 Technical Stack (Quick-Glance)

Layer	Technology	Notes
Messaging channel	WhatsApp (via Twilio or Meta WhatsApp Cloud API)	Optimized for short, actionable messages; supports media attachments (e.g., heatmaps).
API layer	FastAPI	Typed request validation and structured routing.
Compute	Google Cloud Run	Stateless containers with horizontal autoscaling.
Task queue	Cloud Tasks	Offloads heavy operations; falls back to in-process background tasks when needed.
Persistence	Firestore	Session and field state; designed for concurrent access.
Geospatial compute	Google Earth Engine	Server-side computation for imagery and derived indices.
Imagery sources	Sentinel-2 (optical), Sentinel-1 (SAR)	Optical for reflectance indices; SAR for cloud-resilient signals and water detection.
AI layer	Gemini (Vertex AI)	Converts tool outputs into farmer-friendly recommendations using structured outputs.

Availability pattern Instances scale horizontally; no cross-request in-memory state assumptions.

Failure containment External API failures are handled with retries and fallback paths where applicable.

Latency control Expensive operations are queued/offloaded to avoid blocking webhook response windows.

Operational observability Structured logs and distributed traces are used for production diagnostics.

3) Geospatial and Environmental Data Stack

Google Earth Engine is the geospatial compute backend.
Sentinel-2 optical imagery is used for vegetation and reflectance-derived indices.
Sentinel-1 SAR imagery is used for cloud-resilient and inundation-related analyses.
Weather and terrain datasets are fused for water, erosion, and planning use-cases.

To control latency and quota pressure, server-side reductions are preferred and repeated client-side fetch loops are avoided.

3.1 Data Pipeline & Indices

The system derives agronomic signals by transforming imagery into indices and aggregating them over the field geometry. Outputs are computed server-side and returned as compact numerical summaries (plus optional heatmaps).

NDVI: vegetation vigor/biomass proxy from Sentinel-2 reflectance.
NDRE: chlorophyll/nitrogen proxy using Sentinel-2 Red Edge bands (useful in dense canopies).
NDWI: canopy/leaf water content proxy using SWIR-sensitive reflectance behavior.
RUSLE: erosion-threat estimation that fuses terrain and rainfall/cover signals.
RVI fallback (SAR): radar-based vegetation signal used when optical imagery is degraded by clouds.

4) Analytical Modules (Public Capability Surface)

Crop health and vigor assessment.
Nitrogen/chlorophyll proxy indicators (including Sentinel-2 Red Edge-based signals).
Water status and stress detection.
Flood/standing-water detection (SAR-friendly paths).
Soil erosion threat estimation.
Yield outlook and weather-informed planning recommendations.
Heatmap-based directed scouting outputs.

4.1 High-Level Flow: Report Generation

User selects an analysis type (for example crop health or water status).
Request is validated, idempotency checked, and routed to the analysis orchestrator.
Geospatial engine computes indices/statistics over the registered field geometry.
AI layer converts structured tool output into a strict template-based response.
Text report is delivered first; optional heatmap/media follows as a second message.

flowchart LR
    user[Farmer on WhatsApp] --> req[Analysis Request]
    req --> validate[Validate + Idempotency Check]
    validate --> route[Route to Analysis Orchestrator]
    route --> geo[Geospatial Compute]
    geo --> ai[Template-Based AI Rendering]
    ai --> text[Send Text Report]
    text --> media[Optional Heatmap / Media]

4.2 High-Level Flow: Field Registration

User starts registration by sending a location and field context.
System validates payload, normalizes identity/session, and requests boundary details.
Boundary/editor input is validated and persisted to field/session records.
Registration confirmation is returned and the field becomes available for analysis.

flowchart LR
    farmer[Farmer] --> pin[Send Location Pin]
    pin --> validateReg[Validate Request]
    validateReg --> boundary[Capture Boundary / Editor Input]
    boundary --> persist[Persist Field + Session State]
    persist --> confirm[Confirm Registration]
    confirm --> ready[Field Ready for Analysis]

5) AI Interpretation Layer

LLM-based interpretation transforms tool outputs into concise agronomic guidance.
Message rendering follows a strict, validated template structure (structured fields and formatting), reducing the risk of free-form hallucinated output.
Response templates prioritize actionability and short mobile-readable structure.
Vision/image analysis is only triggered on explicit photo input paths.
History windows are bounded to control token usage and response latency.

6) Outlier and Change Detection (High-Level)

This layer explains how the system distinguishes normal seasonal variability from actionable anomalies at field and sub-field levels.

Year-by-year outlier detection: Current observations are compared against historical baselines for the same seasonal window to flag unusual deviations.
Field hotspot detection: Spatial analysis highlights localized zones that diverge from field-level behavior, enabling targeted scouting rather than whole-field inspection.
Trend / changepoint detection: Time-series behavior is monitored to identify abrupt directional shifts (for example sudden vigor decline) rather than only static threshold breaches.
Operational objective: Prioritize early warning signals that are robust enough for practical decision support in real farm operations.

7) Data Governance and Storage Characteristics

Conversation/session state is stored in Firestore documents.
Session memory in process is treated as cache only, never source of truth.
Document growth is bounded to preserve read/write performance.
PII handling follows masked logging and minimum necessary retention principles.

8) Reliability and Observability

Operational monitoring is in place to track service health and runtime behavior.
Structured logging is used for production visibility and incident triage.
The architecture utilizes horizontal autoscaling and asynchronous task queuing to maintain service availability during peak demand and varying network conditions.
Release verification includes production checks before and after deployment.

9) Known Constraints and Non-Goals

The system is not a replacement for in-field professional agronomic diagnosis.
Satellite availability/quality can vary due to cloud cover and acquisition cadence.
Outputs are decision support signals, not guaranteed deterministic prescriptions.
This specification intentionally omits internal implementation details and security-sensitive configuration.

10) Integration Surface (High-Level)

Messaging providers for inbound/outbound WhatsApp traffic.
Cloud-native platform services (compute, queueing, persistence).
Earth observation and weather data providers.
LLM runtime for interpretation and conversational response generation.

11) Data Security, Trust and Legal Notice

Data Security & Trust Statement
Arandu Technologies GmbH

At Arandu, we treat agricultural data with the same precision as the crops it represents. Our platform is built on enterprise-grade infrastructure so that while insights remain accessible, data remains protected.

11.1 How We Protect Your Information

Secure Infrastructure: Arandu operates on Google Cloud Platform (GCP) with stateless services and Firestore persistence for session/field state.
Privacy controls: Personally identifiable information (PII) is masked in internal logs and used only as required to support the WhatsApp communication layer.
Channel Integrity: Provider APIs are accessed over HTTPS/TLS when communicating with messaging infrastructure (e.g., Twilio or Meta APIs).
No Automated Prescriptions: Arandu provides decision-support signals. Data and interpretation are provided, while final operational decisions remain with the grower.

11.2 Intellectual Property and Legal Notice

The Arandu system architecture, including its proprietary integration of geospatial indices (NDVI, NDRE, RVI) and LLM-based agronomic interpretation, is the exclusive property of Arandu Technologies GmbH.

Reproduction, distribution, or reverse engineering of the Arandu technical framework, logic flows, or proprietary prompt structures without express written consent is strictly prohibited.

12) Versioning and Change Management

This page tracks the technical profile of Arandu. When architecture, analysis surface, or runtime controls materially change, this document should be updated in the same release cycle.