docs/DOCUMENTATION.md

# CropGuard GH — System Documentation

**Image-Based Crop Disease Detection System for Smallholder Farmers in Ghana**
Final Year Project · Oppong David · BTech Computer Technology, Kumasi Technical University

---

## 1. What this is

CropGuard is the working implementation of the system designed in the project report. A farmer photographs a diseased crop leaf and instantly receives:

- the **disease name** (55 classes across 14 crops cultivated in Ghana),
- a **confidence score**,
- a **severity level** (Early / Moderate / Severe) with colour coding,
- an **urgency level** (Routine / Urgent / Emergency), and
- a numbered list of **treatment steps** plus suggested products.

It ships in **two forms**, both included here:

| Deliverable | File | Use it for |
|---|---|---|
| **Ready-to-use HTML app** | `cropguard.html` | Open in any browser/phone. Works immediately (on-device estimate). No install. Covers all 14 Ghanaian crops when connected to the model. Bilingual (English + Twi toggle). |
| **Full production system** | `cropguard-system/` | The real stack from Chapter 3: trained MobileNetV2 model + FastAPI backend + React frontend. |

The HTML app can **also** connect to the trained backend — open Settings and paste the API URL, or set `localStorage.cropguard_api`. When no server is set it falls back to a genuine on-device colour/lesion analyser so it is never broken.

---

## 2. Architecture

The system follows the three-component client–server model described in §3.3:

```
   ┌─────────────────────────┐         HTTPS / multipart        ┌──────────────────────────┐
   │   Frontend (client)     │  ── POST /predict (image) ──▶    │   Backend (server)        │
   │  React app  OR          │                                  │   FastAPI                 │
   │  single-file HTML        │  ◀── JSON diagnosis ──────       │   ├─ MobileNetV2 model    │
   │  (camera + gallery)      │                                  │   ├─ severity estimator   │
   └─────────────────────────┘                                  │   └─ recommendations.json │
                                                                 └──────────────────────────┘
```

- **Inference runs on the server**, so the model can be updated without users reinstalling anything and old phones still work (§3.3).
- **Communication is a stateless REST API** returning JSON (§3.3).
- **Uploaded images are never stored** — they are processed in memory and discarded (§3.10.2 / §3.13 privacy-by-design).

---

## 3. The model (`backend/train.py`)

A transfer-learning classifier (MobileNetV2 **or** EfficientNetB0, via `--arch`), built as specified in §3.6:

**Accuracy target ~98%.** MobileNetV2 reaches roughly 97–98% on this benchmark; for the full multi-crop set use `--arch efficientnet` (EfficientNetB0), which typically reaches **98–99%**, in line with the published literature (Mohanty et al. 2016 = 99.35%, Ferentinos 2018 = 99.53%). The figure is reported honestly from the held-out test set at the end of training — it is never assumed. Label smoothing, class weighting and field-condition augmentation are included to push real-world accuracy toward the target.

- **Input:** 224×224 RGB, normalised with ImageNet mean/std.
- **Backbone:** MobileNetV2 or EfficientNetB0 pre-trained on ImageNet.
- **Head:** Global Average Pooling → BatchNorm → Dense(512, ReLU, L2=1e-4) → Dropout(0.4) → Dense(softmax).
- **Two-phase fine-tuning (§3.6.3):** Phase 1 trains the head with the backbone frozen (Adam, lr=1e-3, ~20 epochs); Phase 2 unfreezes the top 30% of the backbone (Adam, lr=1e-4, ~30 epochs) with `EarlyStopping` and `ReduceLROnPlateau`.
- **Loss:** categorical cross-entropy with label smoothing (0.05).
- **Class imbalance (§3.7.1):** balanced class weights computed with scikit-learn.
- **Augmentation (§3.5.2):** flip, rotation, zoom, brightness and contrast jitter.

### Dataset layout expected

```
data/
  train/<class_name>/*.jpg
  val/<class_name>/*.jpg
  test/<class_name>/*.jpg
```

Class folder names must match the keys in `recommendations.json`:

```
maize_healthy maize_gls maize_nclb maize_rust maize_msv maize_faw
cassava_healthy cassava_cmd cassava_cbsd cassava_cbb
tomato_healthy tomato_early tomato_late tomato_wilt tomato_septoria tomato_tylcv
cocoa_healthy cocoa_blackpod cocoa_cssvd cocoa_capsid
cashew_healthy cashew_anthracnose cashew_gumosis cashew_leafminer
plantain_healthy plantain_sigatoka plantain_bbtv plantain_panama
yam_healthy yam_anthracnose yam_mosaic
pepper_healthy pepper_bacterialspot pepper_anthracnose
cowpea_healthy cowpea_blight cowpea_mosaic cowpea_cercospora
groundnut_healthy groundnut_leafspot groundnut_rosette groundnut_rust
rice_healthy rice_blast rice_blb rice_brownspot
okra_healthy okra_yvmv okra_leafspot
gardenegg_healthy gardenegg_wilt gardenegg_leafspot
mango_healthy mango_anthracnose mango_bacterialspot
```

**Covering all crops:** the system is not limited to a fixed list. To add any
further crop, drop a labelled folder of its images into `train/`, `val/` and
`test/`, add a matching record to `recommendations.json`, and retrain — no code
change is required.

Recommended sources (§3.4), Ghana-relevant: the **CCMT dataset** (Cashew, Cassava, Maize, Tomato — field images collected in Ghana), **cassava** disease datasets, **cocoa** (CRIG/COCOBOD imagery), the **rice / cowpea / groundnut** sets from African research programmes, and **PlantVillage/PlantDoc** for tomato, pepper and mango. Locally collected field photographs are added where possible.

### Train

```bash
cd backend
pip install -r requirements.txt
python train.py --data ./data --arch efficientnet --epochs-head 20 --epochs-fine 30
# -> model/crop_model.keras  and  model/classes.json
```

---

## 4. The backend API (`backend/app.py`)

```bash
cd backend
uvicorn app:app --host 0.0.0.0 --port 8000
```

Interactive docs are auto-generated at `http://localhost:8000/docs`.

| Method | Endpoint | Returns |
|---|---|---|
| GET | `/health` | `{"status":"ok","model_loaded":bool}` |
| GET | `/diseases` | the full treatment knowledge base |
| POST | `/predict` | diagnosis JSON (below) |

**`POST /predict`** — send `multipart/form-data` with field `file` = the image.

```json
{
  "class_id": "tomato_late",
  "confidence": 0.94,
  "severity": "moderate",
  "diseased_ratio": 0.42,
  "disease": {
    "crop": "Tomato",
    "name": "Late Blight",
    "cause": "An aggressive water-mould (Phytophthora infestans)...",
    "treatment": ["Act today...", "..."],
    "products": ["Chlorothalonil", "Mancozeb", "Metalaxyl-M"]
  }
}
```

**Severity (§3.8)** is computed by `estimate_severity()` using colour thresholding: it measures the ratio of chlorotic (yellow), necrotic (dark) and lesion (brown) pixels to total leaf pixels, then maps `<0.20 → early`, `<0.55 → moderate`, else `severe`.

---

## 5. The React frontend (`frontend/src/CropGuard.jsx`)

The four-step flow from §3.10.4 — **home → preview → loading → result** — with camera capture, gallery upload, confidence bar, colour-coded severity, treatment steps and the safety disclaimer.

```bash
cd frontend
npm create vite@latest . -- --template react   # if starting fresh
npm install
echo "VITE_API_URL=http://localhost:8000" > .env
# drop CropGuard.jsx into src/ and render <CropGuard/> from App.jsx
npm run dev
```

---

## 6. The standalone HTML app (`cropguard.html`)

A single self-contained file — open it directly on a phone or host it anywhere static (Netlify, GitHub Pages, a CDN). It implements the full farmer UI in English **and Twi**, with:

- camera capture + gallery upload,
- a **real on-device analyser** (canvas pixel analysis of green vs. chlorotic/necrotic/lesion area) so it works with zero backend,
- **optional backend mode** — if `localStorage.cropguard_api` is set to your FastAPI URL it sends images to the trained model instead,
- severity colour coding, urgency icons, treatment steps, product suggestions, disease explanation, feedback and share.

To point it at the real model, run in the browser console:
```js
localStorage.setItem('cropguard_api', 'https://your-api-host:8000');
```

> **Note on the on-device fallback:** the heuristic analyser is honest and deterministic (it inspects actual leaf colour and damage area), but it is **not** the trained CNN. For graded, research-quality accuracy, connect the HTML app to the FastAPI backend running your trained model.

---

## 7. Deployment notes (§3.11)

- **Backend:** MobileNetV2 is light (~300M multiply-adds/inference) so a CPU-only instance serves several concurrent users; CORS and HTTPS should be enabled in production.
- **Frontend:** ship the React build or `cropguard.html` as static files behind a CDN for fast loads across Ghana.
- **Privacy:** no login, no accounts, no image storage.

---

## 8. Mapping to the report

| Report section | Where it lives in the code |
|---|---|
| §3.3 System architecture | client–server split (frontends ↔ `app.py`) |
| §3.4 Dataset | `train.py` `image_dataset_from_directory` layout |
| §3.5 Preprocessing & augmentation | `standardise()`, `build_augmenter()` |
| §3.6 MobileNetV2 + custom head + 2-phase fine-tune | `build_model()`, `main()` |
| §3.7 Loss, class weights, LR schedule | `class_weights_from_dir()`, callbacks |
| §3.8 Severity classification | `estimate_severity()` (backend) / `analyseOnDevice()` (HTML) |
| §3.9 Treatment recommendations | `recommendations.json` |
| §3.10 Web app & mobile-first UI | `cropguard.html`, `CropGuard.jsx` |
| §3.13 Privacy / ethics | in-memory image handling, no storage |