HealthyCropping – Offline crop disease diagnosis on Android (TFLite and RAG)

Smallholder and medium-scale producers of coffee (Coffea arabica / canephora), cacao (Theobroma cacao), and banana (Musa spp.) in Central America frequently work in mountainous or rural plots with intermittent or zero cellular connectivity. Identifying pathogens early—such as coffee leaf rust (Hemileia vastatrix), cacao frosty pod rot (Moniliophthora roreri), or banana black Sigatoka (Pseudocercospora fijiensis)—is critical to timing cultural controls and preventing yield loss, yet cloud-only diagnostic tools fail in the field when connectivity drops.

HealthyCropping (com.keylorpineda.healthycropping) is an open-source, non-commercial, offline-first Android application. It runs quantized computer vision models directly on the phone with sub-50ms inference, records scans and plot geometries locally in SQLite, and synchronizes with a FastAPI backend and Gemini RAG advisory layer grounded in certified institutional literature (ICAFE, CATIE, CORBANA) once connectivity is restored.

Agronomic Disclaimer: HealthyCropping is a non-commercial, open-source decision-support tool designed initially for Costa Rica. It supports field decisions and does not replace a certified agronomist or phytosanitary laboratory. Always consult an agricultural professional before applying agrochemicals or removing plants.

The project is structured into 9 execution phases according to docs/PLAN.md:

flowchart LR A["1. Select Crop\n(Coffee / Cacao / Banana)"] --> B["2. Capture Photo\n(Guided framing tips)"] B --> C["3. On-Device Preprocessing\n(224x224 RGB + normalize)"] C --> D["4. Offline TFLite Inference\n(MobileNetV3 float16 / INT8)"] D --> E["5. Instant Local Result\n(Class, Severity, SQLite)"] E -. "Optional when online" .-> F["6. Cloud Sync & Gemini RAG\n(FastAPI + Cited Manuals)"]

Loading

Crop Selection: The user selects Coffee (leaf underside), Cacao (pod), or Banana (leaf) prior to scanning so a dedicated specialist model runs for that crop.

Offline On-Device Inference: The captured photo is resized to 224x224, decoded to raw RGB, normalized with exact training statistics, and evaluated locally in < 50ms using react-native-fast-tflite.

Actionable Triage & Thresholding: If confidence falls below the calibrated validation threshold, the app instructs the user to retake the photo. Otherwise, it reports predicted class, severity level, confidence, and recommended triage action (healthy, watch, or act now).

Local Persistence & Optional Sync: Scans, farms, and plots are stored locally in expo-sqlite with client-generated UUIDs. Account creation is optional and used solely to synchronize records idempotently through the FastAPI backend (api/).

Grounded RAG Advisory: When online, the backend retrieves passages from official technical manuals (ICAFE for coffee, CATIE for cacao, CORBANA for banana) and utilizes Gemini to summarize recommendations without hallucinated chemical remedies.

Supported Crops & Model Architectures

One fine-tuned MobileNetV3 model is trained, evaluated, and exported per crop (224x224 RGB input, quantized TFLite < 10 MB):

Tensor preprocessing parity between Python (ml/) and React Native (app/src/ml/) is enforced by shared fixture tests.

healthycropping/ ├── app/ # Expo React Native (Android, pnpm): on-device TFLite, SQLite, UI ├── api/ # Python 3.12 (uv): FastAPI, Firebase Admin, Cloudinary, RAG ├── ml/ # Python 3.12 (uv): data preprocessing, training, eval, TFLite export └── docs/ # ARCHITECTURE, PLAN, MODEL_CARD, DATASETS, EXPERIMENTS, DEVLOG

Workspace Stack Purpose

app/ React Native 0.76, Expo 52, TypeScript, SQLite, TFLite Offline mobile application for Android

api/ Python 3.12, FastAPI, Firebase Admin, Cloudinary, Gemini Sync endpoints, token verification & RAG advisory

ml/ Python 3.12, TensorFlow 2.16, TFLite, Pillow Training pipelines, evaluation & quantized edge export

Run Locally

Prerequisites

Mobile: Node.js 20+, pnpm (configured with node-linker=hoisted), Android SDK.

Backend & ML: Python 3.12, uv package manager.

1. Mobile App (app/, pnpm only)

cd app pnpm install pnpm typecheck pnpm lint pnpm test pnpm start

2. Backend API (api/, uv only)

cd api uv sync --all-extras uv run ruff check . uv run mypy src tests uv run pytest uv run uvicorn src.main:app --reload

3. Machine Learning (ml/, uv only)

cd ml uv sync --all-extras uv run ruff check . uv run mypy src scripts tests uv run pytest

Open Source Contributions & Community

Contributions are welcome. Please check our open issues and guidelines before opening a pull request:

Decision Support Only: Visual symptoms cannot distinguish every microscopic pathogen strain or nutrient deficiency. Laboratory diagnostics remain necessary for high-impact interventions.

Field Lighting Sensitivity: Direct specular glare on wet foliage or extreme motion blur can reduce model confidence.

Backend Cold Starts: The optional FastAPI synchronization API runs on Render's free tier (sleeps after 15 minutes of inactivity). Core disease diagnosis and SQLite storage operate 100% offline on the phone and are never affected.

Dataset Credits & Licenses

The MIT license in LICENSE applies solely to the source code in this repository. Training datasets remain under their respective upstream licenses documented in docs/DATASETS.md: