Skip to content

Architecture

Jump to bottom
George-Kariuki edited this page Nov 4, 2025 · 2 revisions

🏗️ AgriScan System Architecture

This page provides a full overview of the AgriScan architecture — how the mobile app, backend, database, and AI model work together to deliver instant, offline-friendly plant disease detection.

🌾 High-Level Overview

AgriScan is built as a mobile-first AI system that combines local inference, offline persistence, and cloud sync.

The design principles:

  • ⚡ Speed: Instant on-device predictions (no lag or server wait)
  • 🌐 Offline-first: Farmers can still scan without internet
  • 🧩 Modularity: Each layer (AI, API, App) can evolve independently
  • 🔐 Security: Minimal data stored, secure sync via Supabase

🧱 Core Architecture Diagram

        ┌────────────────────────────┐
        │        Flutter App         │
        │  - Camera Capture          │
        │  - Offline Hive DB         │
        │  - History & Sync Queue    │
        │  - Treatment UI (Planned)  │
        └──────────────┬─────────────┘
                       │
                       ▼
        ┌────────────────────────────┐
        │        FastAPI API         │
        │  - /predict endpoint       │
        │  - /sync (future)          │
        │  - AI model inference      │
        └──────────────┬─────────────┘
                       │
                       ▼
        ┌────────────────────────────┐
        │       TensorFlow Model     │
        │  - cassava.tflite          │
        │  - 5 disease classes       │
        │  - Confidence scoring      │
        └──────────────┬─────────────┘
                       │
                       ▼
        ┌────────────────────────────┐
        │     Supabase / Postgres    │
        │  - Users, farms, scans     │
        │  - Auth & analytics        │
        └────────────────────────────┘

🧩 Components Breakdown

1. Flutter Mobile App

  • Cross-platform (Android/iOS) built with Flutter 3.24
  • Handles:
    • Camera capture (camera plugin)
    • Local storage using Hive
    • Offline queueing and sync
    • Display of prediction results and history
  • Planned upgrades:
    • SMS alerts for offline notifications
    • Multi-crop toggle
    • Treatment recommender UI

2. FastAPI Backend

  • Lightweight backend for model inference and data sync
  • Runs as a REST API with:
    • /api/v1/predict: Accepts base64 image → returns disease + confidence
    • /api/v1/sync (planned): Push/pull logs between mobile and Supabase
  • Includes:
    • Model loading from models/cassava.tflite
    • Pillow/OpenCV for preprocessing
    • Automated tests via pytest
    • Deployed with Docker + Uvicorn

3. AI Model

  • Based on TensorFlow MobileNetV2 architecture

  • Converted from .h5 → .tflite for mobile performance

  • Predicts five cassava leaf disease classes:

    1. Cassava Bacterial Blight (CBB)
    2. Cassava Brown Streak Disease (CBSD)
    3. Cassava Green Mottle (CGM)
    4. Cassava Mosaic Disease (CMD)
    5. Healthy Leaf

  • Model files:

    • models/cassava.tflite
    • models/labels.txt

  • Approx. size: 12–15 MB

  • Runtime: TensorFlow Lite + NumPy + Pillow

4. Database Layer

  • Supabase (PostgreSQL) for cloud sync and analytics
  • Mobile app uses Hive as local satellite DB:
    • Caches predictions, timestamps, and images
    • Handles offline-first operations
    • Syncs via API when network is available
Database Role Location
Hive Local cache Device
Supabase Cloud sync Backend

5. Offline + Sync Logic

AgriScan follows an Offline-First architecture:

  1. Scan → Predict (locally using tflite)
  2. Store scan result in Hive DB
  3. Background sync when online
  4. API pushes scan data to Supabase

This ensures usability even in rural areas with weak connections.

6. CI/CD Pipeline

Automated with GitHub Actions:

  • Lint + test both api/ and app/ folders
  • Run unit tests with pytest and flutter test
  • Build Docker container on main branch
  • Tag + deploy (future step)

Example workflow file: .github/workflows/test.yml

7. Security

  • Minimal PII stored (no sensitive user data)
  • Optional Supabase auth for farmer accounts
  • Future plans:
    • Encrypted sync tokens
    • Role-based access (Admin / Field Agent)

🧠 Data Flow Summary

Step Process Layer
1 Farmer captures photo Flutter Camera
2 Image sent to backend FastAPI
3 Model predicts class TensorFlow
4 Result sent to app API Response
5 App stores to Hive + syncs Local DB → Supabase

🧪 Dev Environment Setup

Tool Version Notes
Python 3.10+ Required for FastAPI
Flutter 3.24+ For app builds
TensorFlow 2.13+ Full version for model
tflite-runtime Optional For lightweight inference
Docker Latest API containerization
Hive Latest Local mobile database

To reproduce locally:

# API
cd api
pip install -r requirements.txt
uvicorn app.main:app --reload

# Flutter app
cd app
flutter pub get
flutter run

🚀 Deployment Strategy

AgriScan is designed for flexible deployment across different environments — from local testing to edge inference on mobile.

Environment Purpose Tech Stack / Tools
🧑‍💻 Local Development & testing FastAPI + Uvicorn (hot reload)
☁️ Cloud (Future) Production deployment Render, Railway, Supabase
📱 Edge (Planned) On-device farm use TensorFlow Lite (mobile inference)

Each deployment option is containerized via Docker, ensuring consistent behavior across environments.
Future plans include lightweight edge deployments for farm kits (solar-powered mobile devices).

📦 Repository Structure

AgriScan/
├── api/
│   ├── app/
│   │   ├── main.py
│   │   ├── routers/
│   │   └── models/
│   ├── tests/
│   └── requirements.txt
│
├── app/
│   ├── lib/
│   │   ├── main.dart
│   │   ├── models/
│   │   ├── screens/
│   │   └── services/
│   └── pubspec.yaml
│
├── models/
│   ├── cassava.tflite
│   ├── labels.txt
│   └── convert_to_tflite.py
│
├── docs/
│   ├── architecture.png
│   └── roadmap.md
│
├── .github/
│   └── workflows/
│       └── test.yml
│
├── LICENSE
└── README.md

📁 Structure Notes

  • /api/ → FastAPI backend and ML inference logic
  • /app/ → Flutter mobile app (offline-first)
  • /models/ → Trained models, conversion scripts, and labels
  • /docs/ → Diagrams, guides, and roadmap
  • /.github/ → CI/CD configuration
  • LICENSE → MIT open-source license
  • README.md → Root documentation summary

📚 References

🌍 Summary

AgriScan merges AI + offline-first mobile tech to empower farmers with real-time crop health insights —
no internet dependency, no complex setup, just a smartphone and smart code.

This modular setup ensures scalability — from a single cassava model today, to a multi-crop ecosystem tomorrow.
It’s designed for African contexts: lightweight, fast, and field-ready.

⚡ Fast. Lightweight. Built for the field.

Clone this wiki locally