How s84v/plant-disease-classifier works
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: api.py API app · predict.py Predict · model.py Model · train.py Train
Components 19
Runtime service
FastAPI app that serves the UI and prediction API.
ML pipeline
Training and inference components for the classifier.
- Model · Transfer-learning classifier architecture and weight-loading logic.
src/model.py - Config · Central hyperparameters, class mapping, and input-size configuration.
src/config.py - Data prep · Shared image transform and dataset preparation logic used for training and serving consistency.
src/data.py - Train · Orchestrates epochs, checkpoints, and the offline training workflow.
src/train.py - Engine · Core train/validation step logic used by the training pipeline.
src/engine.py
Packaged assets
Model-adjacent data bundled with the service.
- Disease info · Loads disease details and enriches predictions with symptoms, causes, treatment, and prevention.
src/disease_info.py - Metadata · Class-to-disease-detail mapping packaged with the repository.
data/disease_metadata.json
Browser UI
Static frontend served by the backend.
- Index page · Single-page browser entry point for image upload and results display.
static/index.html - Styles · Presentation layer for the web interface.
static/css/styles.css - App JS · Client-side upload, request, and result-rendering behavior.
static/js/app.js
Quality
Tests and offline evaluation outputs.
- Evaluate · Offline metric computation and visual analysis for model assessment.
src/evaluate.py - API tests · Exercises success and failure paths for the serving boundary.
tests/test_api.py - Test assets · Images and malformed inputs used for deterministic API testing.
tests/assets - Outputs · Post-training reports, metrics, and diagnostic plots.
outputs
Project ops
Containerization and environment setup.
- Dockerfile · Single-container deployment definition for the service.
Dockerfile - Dependencies · Pinned runtime requirements for the application.
requirements.txt - Env spec · Alternative environment specification for local setup.
environment.yml
Connections 20
- 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.