How borispanasenko/plant-disease-classifier-api works
1. Overall shape
- This is a single-process FastAPI application with three main concerns: image inference, metadata lookup, and detection history persistence.
- The repo is organized as a small monolith rather than separate services: API code in app/, model artifacts in models/, training scripts in training/, seed/data sources in data/ and db_scripts/, and a static test UI in public/.
2. Request entrypoint
- run.py is the launch point for the application, and the backend is intended to run under Uvicorn.
- app/main.py is the central API assembly point where routes such as /analyze, /detections, and /diseases/{disease_id} are exposed.
3. Image analysis flow
- The /analyze endpoint receives a multipart image upload from the client.
- The image is validated and processed, then passed into the inference layer in app/ml_model.py, which loads the trained PyTorch ResNet-34 classifier and produces a disease label plus confidence score.
- The prediction is then enriched with human-readable disease metadata before being returned.
4. Inference subsystem
- app/ml_model.py is the core machine-learning boundary.
- It likely owns model loading from the models/ directory, image preprocessing with Pillow/torchvision, and prediction post-processing into the class names used by the API.
- This keeps the ML artifact and the web layer decoupled: the API calls into the inference module, but does not embed training logic.
5. Persistence subsystem
- The application stores detection events in a SQLite database.
- app/models.py defines the data model/schema, while the runtime uses SQLAlchemy plus async DB access via aiosqlite according to the README.
- Detection history is exposed through GET /detections, which reads from the database rather than recomputing inference.
6. Disease metadata subsystem
- Disease descriptions and treatment recommendations live outside the database logic in data/diseases_data.py.
- db_scripts/seed_db.py appears to populate the SQLite database with this reference data so API responses can include the disease name, description, and treatment.
- This is a separate content source from prediction results: the model predicts the class, then the metadata layer maps that class to explanatory information.
7. Training pipeline
- training/prepare_data.py and training/train_model.py form an offline ML workflow.
- These scripts are not part of request handling; they prepare the dataset, train the classifier, and generate artifacts stored under models/.
- This separation is important: production inference depends on trained outputs, while training can be rerun independently for experimentation.
8. Static frontend
- public/index.html and public/script.js provide a minimal browser-based client for manual testing.
- The frontend sends images to the backend’s /analyze endpoint and can display prediction results without requiring a separate frontend build system.
- It is a convenience layer, not a core dependency of the API.
9. Filesystem roles
- uploads/ is reserved for incoming image files, suggesting the backend persists uploaded content temporarily or for inspection.
- models/ holds the trained model files used at inference time.
- data/ contains the disease reference content, while db_scripts/ contains bootstrap logic for initializing the database state.
10. Configuration and runtime boundaries
- app/config.py likely centralizes environment-driven settings such as the SQLite connection string.
- app/__init__.py and utils/__init__.py make the package structure explicit; utils/smart_sleep.py is a small helper module but not a primary architectural boundary.
- The key runtime boundary is between HTTP/API handling, ML inference, and database persistence: requests enter through FastAPI, are classified by PyTorch, then enriched and stored in SQLite before being returned to the client.
Main entry points: main.py API app · diseases_data.py Disease data · ml_model.py Classifier · seed_db.py Seed DB
Components 18
API runtime
FastAPI application entrypoint, routing, and request handling.
- Run app · Launches the FastAPI server.
run.py - API app · Creates the application and exposes the main HTTP routes.
app/main.py - Config · Centralized runtime configuration and environment settings.
app/config.py - Analyze · Accepts an image upload and returns a prediction response.
app/main.py - Detections API · Serves stored detection history from the database.
app/main.py - Disease API · Returns metadata for a disease identifier.
app/main.py - Uploads · Temporary storage for incoming image files.
Inference
Model loading and image classification boundary.
- Classifier · Loads the trained model and produces labels and confidence scores.
app/ml_model.py - Preprocess · Validates and transforms uploaded images for inference.
app/ml_model.py - Model files · Stored weights and supporting files used at inference time.
Persistence
Database schema and detection history storage.
- DB schema · Defines the persistence schema for detection history.
app/models.py - History store · Runtime database layer used to persist and read detections.
Content
Disease reference data and database seeding.
- Seed DB · Populates the database with reference disease records.
db_scripts/seed_db.py - Disease data · Human-readable disease descriptions and treatments.
data/diseases_data.py
Training
Offline dataset preparation and model training pipeline.
- Prepare data · Builds training inputs from source data.
training/prepare_data.py - Train model · Trains the classifier and produces artifacts.
training/train_model.py
Static UI
Minimal browser client for manual testing.
- Test UI · Minimal browser client for manual testing.
public/index.html - Client script · Sends images to the analysis endpoint and displays results.
public/script.js
Connections 22
- Run app → API app: starts · Uvicorn launches the FastAPI application.
- API app → Config: loads · Routes and runtime settings use centralized configuration.
- API app → Analyze: exposes · Main image classification endpoint.
- API app → Detections API: exposes · History retrieval endpoint.
- API app → Disease API: exposes · Disease metadata lookup endpoint.
- API app → Uploads: uses · Incoming files may be staged on disk.
- Analyze → Preprocess: validates · Uploaded images are checked and transformed before inference.
- Analyze → Classifier: predicts · Endpoint delegates classification to the ML boundary.
- Analyze → Disease data: enriches · Prediction is mapped to readable disease information.
- Analyze → History store: stores · Detection event is persisted for later retrieval.
- Classifier → Model files: loads · Inference uses trained weights and related files.
- Classifier → Preprocess: uses · Classifier expects preprocessed image tensors.
- Detections API → History store: reads · Returns persisted detection history.
- Disease API → Disease data: looks up · Serves explanatory disease content.
- DB schema → History store: defines · Schema drives the SQLite persistence layer.
- Seed DB → Disease data: seeds · Bootstrap script loads reference disease records.
- Seed DB → History store: initializes · Populates the database with seed content.
- Prepare data → Disease data: consumes · Training data preparation uses source data and labels.
- Prepare data → Train model: feeds · Prepared data is used for model training.
- Train model → Model files: writes · Training produces the deployed model artifacts.
- Test UI → Client script: includes · Static page loads client-side request logic.
- Client script → Analyze: calls · Browser client submits images to the analysis endpoint.