# raul-akhuli/menstrual-health-detection-system architecture

> Architecture diagram of the GitHub repository raul-akhuli/menstrual-health-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raul-akhuli/menstrual-health-detection-system
- Repository: https://github.com/raul-akhuli/menstrual-health-detection-system

## Overview

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: [`backend/predict.py`](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/predict.py) (Predictor), [`frontend/app.js`](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/app.js) (App Logic), [`frontend/index.html`](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/index.html) (Static UI), [`backend/models/vgg16_best.keras`](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/models/vgg16_best.keras) (Model File)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser UI<br/>client"))
  node_ui_assets["Static UI<br/>frontend assets<br/>[index.html]"]
  node_ui_logic["App Logic<br/>client script<br/>[app.js]"]
  node_ui_config["Config<br/>[config.js]"]
end

subgraph group_backend["Backend"]
  node_api_server["API Server<br/>http service<br/>[main.py]"]
  node_request_api["Request API<br/>upload endpoint"]
  node_inference_core["Predictor<br/>inference pipeline<br/>[predict.py]"]
  node_preprocess["Preprocess<br/>image prep"]
  node_model_loader["Model Loader<br/>keras runtime"]
  node_model_file["Model File<br/>artifact<br/>[vgg16_best.keras]"]
  node_label_map["Class Names<br/>artifact<br/>[class_names.json]"]
  node_api_tests["API Tests<br/>contract test<br/>[test_api.py]"]
end

subgraph group_offline["Offline ML"]
  node_train_pipeline["Training<br/>offline pipeline<br/>[train.py]"]
  node_eval_pipeline["Evaluation<br/>offline pipeline<br/>[evaluate.py]"]
end

subgraph group_deployment["Deployment"]
  node_deployment_cfg["Deploy Config<br/>hosting config<br/>[vercel.json]"]
end

node_browser -->|"loads"| node_ui_assets
node_ui_assets -->|"boots"| node_ui_logic
node_ui_logic -->|"reads"| node_ui_config
node_ui_logic -->|"uploads image"| node_request_api
node_api_server -->|"exposes"| node_request_api
node_request_api -->|"routes to"| node_inference_core
node_inference_core -->|"prepares"| node_preprocess
node_inference_core -->|"uses"| node_model_loader
node_model_loader -->|"loads"| node_model_file
node_inference_core -->|"maps labels"| node_label_map
node_request_api -.->|"verified by"| node_api_tests
node_train_pipeline -->|"produces"| node_model_file
node_train_pipeline -->|"feeds"| node_eval_pipeline
node_eval_pipeline -.->|"validates"| node_model_file
node_deployment_cfg -->|"deploys"| node_api_server
node_deployment_cfg -->|"serves"| node_ui_assets

click node_ui_assets "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/index.html"
click node_ui_logic "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/app.js"
click node_ui_config "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/config.js"
click node_api_server "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/main.py"
click node_inference_core "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/predict.py"
click node_model_file "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/models/vgg16_best.keras"
click node_label_map "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/models/class_names.json"
click node_train_pipeline "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/train.py"
click node_eval_pipeline "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/evaluate.py"
click node_api_tests "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/test_api.py"
click node_deployment_cfg "https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/vercel.json"

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_browser,node_ui_assets,node_ui_logic,node_ui_config toneBlue
class node_api_server,node_request_api,node_inference_core,node_preprocess,node_model_loader,node_model_file,node_label_map,node_api_tests toneAmber
class node_train_pipeline,node_eval_pipeline toneMint
class node_deployment_cfg toneRose
```

## Components

### Frontend

Browser UI and static client assets.

- **Browser UI**: client · User-facing entry point for uploading an image and viewing the prediction.
- [Static UI](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/index.html): frontend assets · Presentation layer for the client interface. · `frontend/index.html`
- [App Logic](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/app.js): client script · Handles upload, preview, status updates, and response rendering. · `frontend/app.js`
- [Config](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/frontend/config.js): client config · Centralizes API endpoint and runtime settings for the frontend. · `frontend/config.js`

### Backend

Python inference service and ML runtime.

- [API Server](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/main.py): http service · Backend entrypoint that exposes the prediction endpoint and request handling. · `backend/main.py`
- **Request API**: upload endpoint · Accepts image uploads and returns inference results.
- [Predictor](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/predict.py): inference pipeline · Loads the model, preprocesses images, runs inference, and formats labels. · `backend/predict.py`
- **Preprocess**: image prep · Decodes, resizes, and normalizes incoming images for the CNN.
- **Model Loader**: keras runtime · Loads the deployed Keras model artifact for serving.
- [Model File](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/models/vgg16_best.keras): artifact · Packaged trained CNN used for live inference. · `backend/models/vgg16_best.keras`
- [Class Names](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/models/class_names.json): artifact · Maps model outputs to human-readable condition labels. · `backend/models/class_names.json`
- [API Tests](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/test_api.py): contract test · 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](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/train.py): offline pipeline · Trains the CNN that is later exported as the deployable artifact. · `backend/train.py`
- [Evaluation](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/backend/evaluate.py): offline pipeline · Validates model quality after training. · `backend/evaluate.py`

### Deployment

Hosting and packaging configuration.

- [Deploy Config](https://github.com/raul-akhuli/menstrual-health-detection-system/blob/main/vercel.json): hosting config · Deployment settings for the hosted frontend/backend integration. · `vercel.json`

## Connections

- 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.
