How raul-akhuli/menstral-health-detection-system works
1. High-level shape
- This repository is split into two main runtime surfaces: a static browser frontend in frontend/ and a Python ML backend in backend/.
- The system is centered on a single job: accept an uploaded menstrual blood image, preprocess it, run a trained classifier, and return a health-condition prediction.
2. User-facing frontend
- frontend/index.html, frontend/styles.css, and frontend/app.js implement the browser UI.
- frontend/config.js likely contains the backend API base URL or environment-specific endpoint configuration.
- The frontend’s job is limited to file upload, calling the API, and rendering the prediction result and any confidence/feedback.
3. Backend request entrypoint
- backend/main.py is the primary application entrypoint and is likely the HTTP API server (the README suggests Flask).
- This is the boundary between the browser and the ML system: it receives the uploaded image, validates it, and delegates inference.
4. Inference pipeline
- backend/predict.py appears to encapsulate the actual prediction workflow.
- This layer is where image preprocessing and model invocation happen: resizing/normalization, loading the trained Keras model, running inference, and mapping numeric outputs to human-readable labels.
5. Model artifacts
- backend/models/vgg16_best.keras is the trained CNN model artifact used at runtime.
- backend/models/class_names.json stores the label mapping used to convert model outputs into condition names.
- These files are the stable runtime dependencies of the inference path; they separate deployed prediction from training code.
6. Training and evaluation boundary
- backend/train.py and backend/evaluate.py are offline ML lifecycle scripts, not part of the user request path.
- They define the model-development side of the architecture: dataset ingestion, training, validation, and performance measurement.
- In an architecture diagram, these belong on a separate “model development” lane from the live inference flow.
7. API verification
- backend/test_api.py suggests a lightweight smoke-test or endpoint test harness for the backend.
- This is useful to show as a quality gate around the API layer, distinct from model evaluation.
8. Technology stack that materially affects architecture
- The backend is Python-based and uses TensorFlow/Keras for the trained CNN model.
- The frontend is plain HTML/CSS/JavaScript, so the client is lightweight and browser-native.
- backend/requirements.txt and backend/package.json / package-lock.json indicate the backend has Python dependencies and may also include Node-based tooling or packaging support.
9. Data flow
- The main runtime flow is:
- user uploads image in the browser,
- frontend sends the file to the backend API,
- backend preprocesses the image,
- backend loads the Keras model and predicts the class,
- backend returns the predicted condition,
- frontend displays the result to the user.
- No database or user account system is present in the file tree, so the architecture is stateless and request-driven.
10. Deployment boundary
- vercel.json shows the repo is configured for Vercel deployment.
- The project appears designed to serve the frontend publicly and connect it to the backend API in a deployment-friendly way, rather than relying on a traditional always-on server stack.
- DEPLOYMENT.md, MODEL_DEPLOYMENT.md, and KERAS_INTEGRATION_FIX.md suggest deployment and model-serving details were important enough to document separately.
11. What to draw in an architecture diagram
- Draw three main boxes:
- Browser UI (frontend/)
- Backend API / inference service (backend/main.py, predict.py)
- Model artifacts (backend/models/)
- Then add a separate offline lane for training/evaluation (train.py, evaluate.py) that produces the model artifact consumed by the live inference service.
12. Primary architectural constraint
- The trained model file is a hard runtime dependency: without vgg16_best.keras and class_names.json, the service cannot map predictions to health labels.
- That makes the system model-centric rather than data-centric; the dominant boundary is between offline model creation and online inference.
Main entry points: main.py API Server · app.js App Logic · predict.py Predictor · index.html Browser UI
Components 17
Frontend
Browser-based user interface and API client
- Browser UI · User-facing web interface for image upload and results
frontend/index.html - Styles · Presentation and layout for the browser UI
frontend/styles.css - App Logic · Handles upload flow, API calls, and result rendering
frontend/app.js - Config · Frontend endpoint configuration
frontend/config.js
Backend
Python API and ML inference service
- API Server · Receives image requests and returns predictions
backend/main.py - Predictor · Preprocessing, model loading, inference, and label mapping
backend/predict.py - Preprocess · Resizes and normalizes uploaded images before inference
backend/predict.py - Model Inference · Runs the trained CNN to produce class scores
backend/predict.py - Class Labels · Maps model outputs to human-readable conditions
backend/models/class_names.json - Trained Model · Runtime CNN model used by the service
backend/models/vgg16_best.keras - API Test · Exercises the backend endpoint for basic verification
backend/test_api.py - Python deps · Backend Python package requirements
backend/requirements.txt - Node tooling · Backend package metadata and lockfile for tooling or packaging
backend/package.json
Model Development
Offline training and evaluation pipeline
- Training · Builds the classifier from training data
backend/train.py - Evaluation · Measures model quality during development
backend/evaluate.py
Deployment
Hosting and integration configuration
- Vercel · Deployment configuration for hosting integration
vercel.json - Deploy docs · Operational and integration notes for deployment
DEPLOYMENT.md
Connections 19
- Browser UI → Styles: styled by · UI presentation is defined by the stylesheet
- Browser UI → App Logic: driven by · Browser UI behavior comes from the client script
- App Logic → Config: reads · Client script uses backend endpoint configuration
- App Logic → API Server: uploads image to · Frontend sends the selected image to the backend API
- API Server → Predictor: delegates to · HTTP layer hands request handling to the inference pipeline
- Predictor → Preprocess: preprocesses · Image is prepared before inference
- Predictor → Model Inference: runs · Prepared image is passed into the trained model
- Model Inference → Trained Model: loads · Inference depends on the persisted Keras artifact
- Model Inference → Class Labels: maps to · Numeric outputs are converted to human-readable classes
- Training → Trained Model: produces · Offline training writes the runtime model artifact
- Training → Class Labels: defines · Training establishes the class set used at runtime
- Evaluation → Trained Model: assesses · Evaluation validates the trained model artifact
- API Test → API Server: checks · Smoke tests verify the backend endpoint
- API Server → Python deps: depends on · Server runtime uses Python dependencies
- API Server → Node tooling: supported by · Repository includes Node metadata for tooling or packaging
- Vercel → Browser UI: hosts · Deployment configuration serves the frontend
- Vercel → API Server: routes to · Deployment connects requests to the backend entrypoint
- Deploy docs → Vercel: documents · Deployment docs explain the hosting setup
- Deploy docs → API Server: documents · Docs likely describe backend serving and integration