How raul-akhuli/menstrual-health-detection-system works
1. Overall shape
- This repository is split into two main runtime boundaries: a browser-based frontend in frontend/ and a Python inference backend in backend/.
- The core product flow is: user uploads an image → frontend sends it to the backend → backend preprocesses and runs a CNN model → prediction is returned and displayed.
2. Frontend subsystem
- frontend/index.html, frontend/styles.css, and frontend/app.js form a lightweight static client.
- frontend/config.js likely centralizes backend/API settings so the UI can point to the deployed inference endpoint without hardcoding values in the main app logic.
- The frontend’s job is presentation only: file upload, preview/status handling, and rendering the prediction output.
3. Backend entrypoint and API layer
- backend/main.py is the service entrypoint and is the most likely place where the HTTP API is exposed.
- This layer accepts image upload requests from the frontend, validates them, and coordinates inference.
- backend/test_api.py indicates there is an API contract being exercised independently of the UI, which is useful for verifying request/response shape.
4. Inference pipeline
- backend/predict.py is the inference-focused module: it likely loads the trained Keras model, transforms the incoming image into model-ready input, runs prediction, and maps outputs to human-readable labels.
- backend/models/vgg16_best.keras is the deployed model artifact, so runtime inference depends on this packaged file rather than retraining.
- backend/models/class_names.json is the label mapping used to translate model class indices into the condition names shown to the user.
5. Preprocessing boundary
- The model workflow described in the README matches the code layout: image preprocessing is part of the backend inference path, not the frontend.
- The backend likely handles resizing, normalization, and any image decoding before passing data into the CNN.
6. Training and evaluation are separate from live serving
- backend/train.py is the offline training pipeline used to produce the .keras model artifact.
- backend/evaluate.py is the offline validation/metrics script used to assess model quality after training.
- These scripts are not part of the normal request path, which keeps live inference simpler and reduces runtime dependencies.
7. Model artifact boundary
- The repository stores the deployed model directly under backend/models/, which creates a clear boundary between code and servable ML artifacts.
- This is important for architecture diagrams: the live backend does not depend on a database or external model registry in this repo; it reads local packaged artifacts.
8. Deployment and packaging
- vercel.json suggests the app is configured for Vercel deployment.
- backend/package.json and backend/package-lock.json indicate there is also Node-based deployment/runtime packaging in the backend area, likely to support the Vercel build/runtime environment.
- In architecture terms, the repo is designed for a hosted frontend with a backend endpoint that can be deployed alongside it.
9. External libraries and runtime stack
- The README and filenames point to a Python ML stack: TensorFlow/Keras, plus common image/array tooling such as OpenCV and NumPy.
- The frontend is plain HTML/CSS/JavaScript, so there is no heavy client framework shaping the architecture.
10. What is not present
- There is no evidence in the tree of a database, user accounts, long-term storage, message queue, or background job system.
- That means the system is best drawn as a single-request inference service rather than a data platform: request in, model prediction out.
11. Useful diagram summary
- The cleanest architecture diagram is:
- Browser UI
- Static frontend assets
- Backend inference API
- Preprocessing + Keras model loader
- Packaged model files and class labels
- Training/evaluation should be shown as a separate offline lane feeding the model artifact used by production inference.
Main entry points: predict.py Predictor · app.js App Logic · index.html Static UI · vgg16_best.keras Model File
Components 15
Frontend
Browser UI and static client assets.
- Browser UI · User-facing entry point for uploading an image and viewing the prediction.
- Static UI · Presentation layer for the client interface.
frontend/index.html - App Logic · Handles upload, preview, status updates, and response rendering.
frontend/app.js - Config · Centralizes API endpoint and runtime settings for the frontend.
frontend/config.js
Backend
Python inference service and ML runtime.
- API Server · Backend entrypoint that exposes the prediction endpoint and request handling.
backend/main.py - Request API · Accepts image uploads and returns inference results.
- Predictor · Loads the model, preprocesses images, runs inference, and formats labels.
backend/predict.py - Preprocess · Decodes, resizes, and normalizes incoming images for the CNN.
- Model Loader · Loads the deployed Keras model artifact for serving.
- Model File · Packaged trained CNN used for live inference.
backend/models/vgg16_best.keras - Class Names · Maps model outputs to human-readable condition labels.
backend/models/class_names.json - API Tests · Exercises the backend request and response shape independently of the UI.
backend/test_api.py
Offline ML
Training and evaluation scripts that produce the deployable model artifact.
- Training · Trains the CNN that is later exported as the deployable artifact.
backend/train.py - Evaluation · Validates model quality after training.
backend/evaluate.py
Deployment
Hosting and packaging configuration.
- Deploy Config · Deployment settings for the hosted frontend/backend integration.
vercel.json
Connections 16
- Browser UI → Static UI: loads · The browser opens the static interface.
- Static UI → App Logic: boots · The page loads the client behavior.
- App Logic → Config: reads · Frontend logic uses runtime API settings.
- App Logic → Request API: uploads image · Client sends the selected image to the backend.
- API Server → Request API: exposes · The backend entrypoint serves the prediction API.
- Request API → Predictor: routes to · Requests are passed into the inference pipeline.
- Predictor → Preprocess: prepares · Incoming images are transformed into model-ready inputs.
- Predictor → Model Loader: uses · The predictor depends on the loaded ML model.
- Model Loader → Model File: loads · The runtime reads the packaged Keras artifact.
- Predictor → Class Names: maps labels · Model outputs are translated to human-readable names.
- Request API → API Tests: verified by · API contract can be checked independently.
- Training → Model File: produces · Offline training emits the deployable model artifact.
- Training → Evaluation: feeds · Training output is assessed by evaluation.
- Evaluation → Model File: validates · Evaluation measures the packaged model artifact.
- Deploy Config → API Server: deploys · Hosting configuration points the runtime to the backend service.
- Deploy Config → Static UI: serves · Hosting configuration also serves the frontend assets.