# s84v/plant-disease-classifier architecture

> Architecture diagram of the GitHub repository s84v/plant-disease-classifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s84v/plant-disease-classifier
- Repository: https://github.com/s84v/plant-disease-classifier

## Overview

1. **What this repository is**
   - This is a Dockerized plant-leaf disease classification system.
   - The runtime product is a single FastAPI service that serves both the browser UI and the prediction API.
   - The ML model is a PyTorch ResNet18 classifier trained offline and loaded for inference at startup.

2. **Serving boundary: FastAPI backend**
   - `src/api.py` is the central application boundary.
   - It exposes `GET /` for the web UI, `GET /health` for readiness/monitoring, and `POST /predict` for image classification.
   - The backend is responsible for request validation, file-type checks, image decoding, calling the inference pipeline, and returning structured JSON.

3. **Inference data flow**
   - The request path is: browser upload → multipart file upload → backend validation → image preprocessing → model inference → top-k ranking → metadata enrichment → JSON response.
   - `src/predict.py` likely owns the reusable inference pipeline, while `src/model.py` defines the network architecture and weight loading.
   - The response is not just a label; it includes confidence scores and disease information for the predicted class.

4. **Model subsystem**
   - The core model is a fine-tuned `torchvision` ResNet18 with 38 output classes.
   - `src/model.py` builds the transfer-learning architecture, and `src/config.py` centralizes input size, class mappings, and other runtime hyperparameters.
   - The trained weights are bundled with the project for local inference, so the service does not depend on external model hosting.

5. **Image preprocessing and class mapping**
   - Images are resized to 224×224, converted to tensors, and normalized with ImageNet statistics.
   - The class space is fixed to 38 plant disease/healthy categories across 14 crops.
   - `src/data.py` likely defines the same transform logic for training and validation, keeping preprocessing consistent between training and serving.

6. **Disease metadata enrichment**
   - `data/disease_metadata.json` is a second key asset: it maps predicted classes to human-readable disease details.
   - `src/disease_info.py` loads and serves this metadata so the API can return symptoms, causes, treatment, and prevention advice alongside the model prediction.
   - This is a clear separation between ML classification and domain knowledge enrichment.

7. **Frontend boundary**
   - `static/index.html`, `static/css/styles.css`, and `static/js/app.js` implement a client-side upload-and-results experience.
   - The frontend uploads an image to the API and renders ranked predictions plus disease details in the browser.
   - Static files are served by the same backend, so there is no separate frontend service.

8. **Offline training pipeline**
   - Training is separated from serving and lives under `src/train.py`, `src/engine.py`, and `src/data.py`.
   - `src/train.py` orchestrates epochs and checkpointing; `src/engine.py` likely contains the train/validation step logic; `src/evaluate.py` computes metrics and visualizations.
   - This division keeps training concerns, evaluation artifacts, and inference serving distinct.

9. **Artifacts and evaluation outputs**
   - The `outputs/` directory holds post-training analysis: classification report, metrics JSON, confusion matrix heatmap, per-class accuracy, and misclassification plots.
   - These are offline artifacts used to assess the model, not runtime dependencies.
   - The `notebooks/` directory contains exploratory experiments, reinforcing that experimentation is separate from the production API.

10. **Testing and reliability**
   - `tests/test_api.py` exercises the main request paths, including success, invalid file type, corrupted image, missing file, and wrong HTTP method.
   - `tests/assets/` provides fixture images and malformed inputs to validate error handling deterministically.
   - `src/exceptions.py` and `src/logging_config.py` indicate explicit global error handling and structured logging around the serving layer.

11. **Deployment boundary**
   - The project is intended to run in one container using the provided `Dockerfile`.
   - `requirements.txt` and `environment.yml` describe the Python runtime, while `pytest.ini` supports the test workflow.
   - Operationally, the app is designed as a self-contained local inference service: browser UI and API in the container, model weights and metadata packaged with the repo.

Main entry points: [`src/api.py`](https://github.com/s84v/plant-disease-classifier/blob/main/src/api.py) (API app), [`src/predict.py`](https://github.com/s84v/plant-disease-classifier/blob/main/src/predict.py) (Predict), [`src/model.py`](https://github.com/s84v/plant-disease-classifier/blob/main/src/model.py) (Model), [`src/train.py`](https://github.com/s84v/plant-disease-classifier/blob/main/src/train.py) (Train)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime service"]
  node_src_api["API app<br/>[api.py]"]
  node_src_predict["Predict<br/>inference pipeline<br/>[predict.py]"]
end

subgraph group_ml["ML pipeline"]
  node_src_model["Model<br/>torchvision ResNet18<br/>[model.py]"]
  node_src_config["Config<br/>runtime settings<br/>[config.py]"]
  node_src_data["Data prep<br/>transforms<br/>[data.py]"]
  node_src_train["Train<br/>[train.py]"]
  node_src_engine["Engine<br/>train loops<br/>[engine.py]"]
end

subgraph group_assets["Packaged assets"]
  node_src_disease["Disease info<br/>metadata loader<br/>[disease_info.py]"]
  node_disease_metadata["Metadata<br/>JSON knowledge base"]
end

subgraph group_ui["Browser UI"]
  node_static_index["Index page<br/>HTML UI<br/>[index.html]"]
  node_static_css["Styles<br/>CSS<br/>[styles.css]"]
  node_static_js["App JS<br/>frontend logic<br/>[app.js]"]
end

subgraph group_quality["Quality"]
  node_src_eval["Evaluate<br/>metrics<br/>[evaluate.py]"]
  node_tests_api["API tests<br/>pytest suite<br/>[test_api.py]"]
  node_tests_assets["Test assets<br/>fixtures"]
  node_outputs["Outputs<br/>evaluation artifacts"]
end

subgraph group_ops["Project ops"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_reqs["Dependencies<br/>python deps<br/>[requirements.txt]"]
  node_env["Env spec<br/>conda env<br/>[environment.yml]"]
end

node_src_api -->|"calls"| node_src_predict
node_src_api -->|"enriches"| node_src_disease
node_src_predict -->|"loads"| node_src_model
node_src_predict -->|"uses"| node_src_config
node_src_predict -->|"preprocesses"| node_src_data
node_src_model -->|"reads"| node_src_config
node_src_train -->|"delegates"| node_src_engine
node_src_train -->|"uses"| node_src_data
node_src_train -->|"builds"| node_src_model
node_src_eval -->|"evaluates"| node_src_model
node_src_eval -->|"writes"| node_outputs
node_src_disease -->|"loads"| node_disease_metadata
node_static_js -->|"posts"| node_src_api
node_static_index -->|"uses"| node_static_js
node_static_index -->|"styles"| node_static_css
node_tests_api -->|"covers"| node_src_api
node_tests_api -->|"uses"| node_tests_assets
node_dockerfile -->|"packages"| node_src_api
node_dockerfile -->|"installs"| node_reqs
node_dockerfile -.->|"mirrors"| node_env

click node_src_api "https://github.com/s84v/plant-disease-classifier/blob/main/src/api.py"
click node_src_predict "https://github.com/s84v/plant-disease-classifier/blob/main/src/predict.py"
click node_src_model "https://github.com/s84v/plant-disease-classifier/blob/main/src/model.py"
click node_src_config "https://github.com/s84v/plant-disease-classifier/blob/main/src/config.py"
click node_src_data "https://github.com/s84v/plant-disease-classifier/blob/main/src/data.py"
click node_src_train "https://github.com/s84v/plant-disease-classifier/blob/main/src/train.py"
click node_src_engine "https://github.com/s84v/plant-disease-classifier/blob/main/src/engine.py"
click node_src_eval "https://github.com/s84v/plant-disease-classifier/blob/main/src/evaluate.py"
click node_src_disease "https://github.com/s84v/plant-disease-classifier/blob/main/src/disease_info.py"
click node_disease_metadata "https://github.com/s84v/plant-disease-classifier/blob/main/data/disease_metadata.json"
click node_static_index "https://github.com/s84v/plant-disease-classifier/blob/main/static/index.html"
click node_static_css "https://github.com/s84v/plant-disease-classifier/blob/main/static/css/styles.css"
click node_static_js "https://github.com/s84v/plant-disease-classifier/blob/main/static/js/app.js"
click node_tests_api "https://github.com/s84v/plant-disease-classifier/blob/main/tests/test_api.py"
click node_tests_assets "https://github.com/s84v/plant-disease-classifier/tree/main/tests/assets"
click node_outputs "https://github.com/s84v/plant-disease-classifier/tree/main/outputs"
click node_dockerfile "https://github.com/s84v/plant-disease-classifier/tree/main/Dockerfile"
click node_reqs "https://github.com/s84v/plant-disease-classifier/blob/main/requirements.txt"
click node_env "https://github.com/s84v/plant-disease-classifier/blob/main/environment.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_api,node_src_predict toneBlue
class node_src_model,node_src_config,node_src_data,node_src_train,node_src_engine toneAmber
class node_src_disease,node_disease_metadata toneMint
class node_static_index,node_static_css,node_static_js toneRose
class node_src_eval,node_tests_api,node_tests_assets,node_outputs toneIndigo
class node_dockerfile,node_reqs,node_env toneTeal
```

## Components

### Runtime service

FastAPI app that serves the UI and prediction API.

- [API app](https://github.com/s84v/plant-disease-classifier/blob/main/src/api.py): FastAPI app · Main application boundary exposing UI, health, and prediction endpoints. · `src/api.py`
- [Predict](https://github.com/s84v/plant-disease-classifier/blob/main/src/predict.py): inference pipeline · Reusable request-to-result inference flow: preprocessing, model call, ranking, and formatting. · `src/predict.py`

### ML pipeline

Training and inference components for the classifier.

- [Model](https://github.com/s84v/plant-disease-classifier/blob/main/src/model.py): torchvision ResNet18 · Transfer-learning classifier architecture and weight-loading logic. · `src/model.py`
- [Config](https://github.com/s84v/plant-disease-classifier/blob/main/src/config.py): runtime settings · Central hyperparameters, class mapping, and input-size configuration. · `src/config.py`
- [Data prep](https://github.com/s84v/plant-disease-classifier/blob/main/src/data.py): transforms · Shared image transform and dataset preparation logic used for training and serving consistency. · `src/data.py`
- [Train](https://github.com/s84v/plant-disease-classifier/blob/main/src/train.py): training driver · Orchestrates epochs, checkpoints, and the offline training workflow. · `src/train.py`
- [Engine](https://github.com/s84v/plant-disease-classifier/blob/main/src/engine.py): train loops · Core train/validation step logic used by the training pipeline. · `src/engine.py`

### Packaged assets

Model-adjacent data bundled with the service.

- [Disease info](https://github.com/s84v/plant-disease-classifier/blob/main/src/disease_info.py): metadata loader · Loads disease details and enriches predictions with symptoms, causes, treatment, and prevention. · `src/disease_info.py`
- [Metadata](https://github.com/s84v/plant-disease-classifier/blob/main/data/disease_metadata.json): JSON knowledge base · Class-to-disease-detail mapping packaged with the repository. · `data/disease_metadata.json`

### Browser UI

Static frontend served by the backend.

- [Index page](https://github.com/s84v/plant-disease-classifier/blob/main/static/index.html): HTML UI · Single-page browser entry point for image upload and results display. · `static/index.html`
- [Styles](https://github.com/s84v/plant-disease-classifier/blob/main/static/css/styles.css): CSS · Presentation layer for the web interface. · `static/css/styles.css`
- [App JS](https://github.com/s84v/plant-disease-classifier/blob/main/static/js/app.js): frontend logic · Client-side upload, request, and result-rendering behavior. · `static/js/app.js`

### Quality

Tests and offline evaluation outputs.

- [Evaluate](https://github.com/s84v/plant-disease-classifier/blob/main/src/evaluate.py): metrics · Offline metric computation and visual analysis for model assessment. · `src/evaluate.py`
- [API tests](https://github.com/s84v/plant-disease-classifier/blob/main/tests/test_api.py): pytest suite · Exercises success and failure paths for the serving boundary. · `tests/test_api.py`
- [Test assets](https://github.com/s84v/plant-disease-classifier/tree/main/tests/assets): fixtures · Images and malformed inputs used for deterministic API testing. · `tests/assets`
- [Outputs](https://github.com/s84v/plant-disease-classifier/tree/main/outputs): evaluation artifacts · Post-training reports, metrics, and diagnostic plots. · `outputs`

### Project ops

Containerization and environment setup.

- [Dockerfile](https://github.com/s84v/plant-disease-classifier/tree/main/Dockerfile): container build · Single-container deployment definition for the service. · `Dockerfile`
- [Dependencies](https://github.com/s84v/plant-disease-classifier/blob/main/requirements.txt): python deps · Pinned runtime requirements for the application. · `requirements.txt`
- [Env spec](https://github.com/s84v/plant-disease-classifier/blob/main/environment.yml): conda env · Alternative environment specification for local setup. · `environment.yml`

## Connections

- API app → Predict: calls · Request handling delegates preprocessing and inference to the reusable pipeline.
- API app → Disease info: enriches · Prediction responses are augmented with disease metadata.
- Predict → Model: loads · Inference pipeline uses the trained ResNet18 classifier.
- Predict → Config: uses · Pipeline behavior depends on shared runtime settings and class mapping.
- Predict → Data prep: preprocesses · Image decoding and transforms follow the shared preprocessing contract.
- Model → Config: reads · Model shape and class-space configuration come from centralized settings.
- Train → Engine: delegates · Training orchestration uses reusable step logic.
- Train → Data prep: uses · Training and validation rely on the same dataset/transform pipeline.
- Train → Model: builds · Training constructs the transfer-learning model.
- Evaluate → Model: evaluates · Offline evaluation measures the trained classifier.
- Evaluate → Outputs: writes · Reports and plots are emitted to the outputs directory.
- Disease info → Metadata: loads · Metadata service reads the packaged disease knowledge base.
- App JS → API app: posts · Browser UI uploads images to the prediction endpoint.
- Index page → App JS: uses · The page bootstraps client-side interaction logic.
- Index page → Styles: styles · The page is presented with the shared stylesheet.
- API tests → API app: covers · Tests validate the main request paths and error handling.
- API tests → Test assets: uses · Fixtures provide sample and malformed inputs.
- Dockerfile → API app: packages · Container build packages the serving app and its assets.
- Dockerfile → Dependencies: installs · Runtime dependencies are installed during image build.
- Dockerfile → Env spec: mirrors · Alternative environment specification tracks the same runtime stack.
