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

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

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

## Overview

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: [`backend/main.py`](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/main.py) (API Server), [`frontend/app.js`](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/app.js) (App Logic), [`backend/predict.py`](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py) (Predictor), [`frontend/index.html`](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/index.html) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["Browser UI<br/>static client<br/>[index.html]"]
  node_ui_styles["Styles<br/>css<br/>[styles.css]"]
  node_ui_logic["App Logic<br/>js client<br/>[app.js]"]
  node_ui_config["Config<br/>[config.js]"]
end

subgraph group_backend["Backend"]
  node_api_entry["API Server<br/>http entrypoint<br/>[main.py]"]
  node_predict["Predictor<br/>inference pipeline<br/>[predict.py]"]
  node_preprocess["Preprocess<br/>image prep<br/>[predict.py]"]
  node_infer["Model Inference<br/>keras runtime<br/>[predict.py]"]
  node_labels["Class Labels<br/>label map<br/>[class_names.json]"]
  node_model_file[("Trained Model<br/>keras artifact<br/>[vgg16_best.keras]")]
  node_api_test["API Test<br/>smoke test<br/>[test_api.py]"]
  node_requirements["Python deps<br/>dependency spec<br/>[requirements.txt]"]
  node_node_tooling["Node tooling<br/>js deps<br/>[package.json]"]
end

subgraph group_model_dev["Model Development"]
  node_train["Training<br/>offline ml<br/>[train.py]"]
  node_evaluate["Evaluation<br/>offline ml<br/>[evaluate.py]"]
end

subgraph group_deployment["Deployment"]
  node_vercel["Vercel<br/>deploy config<br/>[vercel.json]"]
  node_docs["Deploy docs<br/>documentation<br/>[DEPLOYMENT.md]"]
end

node_ui -->|"styled by"| node_ui_styles
node_ui -->|"driven by"| node_ui_logic
node_ui_logic -->|"reads"| node_ui_config
node_ui_logic -->|"uploads image to"| node_api_entry
node_api_entry -->|"delegates to"| node_predict
node_predict -->|"preprocesses"| node_preprocess
node_predict -->|"runs"| node_infer
node_infer -->|"loads"| node_model_file
node_infer -->|"maps to"| node_labels
node_train -->|"produces"| node_model_file
node_train -->|"defines"| node_labels
node_evaluate -->|"assesses"| node_model_file
node_api_test -->|"checks"| node_api_entry
node_api_entry -->|"depends on"| node_requirements
node_api_entry -->|"supported by"| node_node_tooling
node_vercel -->|"hosts"| node_ui
node_vercel -->|"routes to"| node_api_entry
node_docs -->|"documents"| node_vercel
node_docs -->|"documents"| node_api_entry

click node_ui "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/index.html"
click node_ui_styles "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/styles.css"
click node_ui_logic "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/app.js"
click node_ui_config "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/config.js"
click node_api_entry "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/main.py"
click node_predict "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py"
click node_preprocess "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py"
click node_infer "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py"
click node_labels "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/models/class_names.json"
click node_model_file "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/models/vgg16_best.keras"
click node_train "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/train.py"
click node_evaluate "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/evaluate.py"
click node_api_test "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/test_api.py"
click node_requirements "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/requirements.txt"
click node_node_tooling "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/package.json"
click node_vercel "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/vercel.json"
click node_docs "https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/DEPLOYMENT.md"

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_ui,node_ui_styles,node_ui_logic,node_ui_config toneBlue
class node_api_entry,node_predict,node_preprocess,node_infer,node_labels,node_model_file,node_api_test,node_requirements,node_node_tooling toneAmber
class node_train,node_evaluate toneMint
class node_vercel,node_docs toneRose
```

## Components

### Frontend

Browser-based user interface and API client

- [Browser UI](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/index.html): static client · User-facing web interface for image upload and results · `frontend/index.html`
- [Styles](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/styles.css): css · Presentation and layout for the browser UI · `frontend/styles.css`
- [App Logic](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/app.js): js client · Handles upload flow, API calls, and result rendering · `frontend/app.js`
- [Config](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/frontend/config.js): js config · Frontend endpoint configuration · `frontend/config.js`

### Backend

Python API and ML inference service

- [API Server](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/main.py): http entrypoint · Receives image requests and returns predictions · `backend/main.py`
- [Predictor](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py): inference pipeline · Preprocessing, model loading, inference, and label mapping · `backend/predict.py`
- [Preprocess](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py): image prep · Resizes and normalizes uploaded images before inference · `backend/predict.py`
- [Model Inference](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/predict.py): keras runtime · Runs the trained CNN to produce class scores · `backend/predict.py`
- [Class Labels](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/models/class_names.json): label map · Maps model outputs to human-readable conditions · `backend/models/class_names.json`
- [Trained Model](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/models/vgg16_best.keras): keras artifact · Runtime CNN model used by the service · `backend/models/vgg16_best.keras`
- [API Test](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/test_api.py): smoke test · Exercises the backend endpoint for basic verification · `backend/test_api.py`
- [Python deps](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/requirements.txt): dependency spec · Backend Python package requirements · `backend/requirements.txt`
- [Node tooling](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/package.json): js deps · Backend package metadata and lockfile for tooling or packaging · `backend/package.json`

### Model Development

Offline training and evaluation pipeline

- [Training](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/train.py): offline ml · Builds the classifier from training data · `backend/train.py`
- [Evaluation](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/backend/evaluate.py): offline ml · Measures model quality during development · `backend/evaluate.py`

### Deployment

Hosting and integration configuration

- [Vercel](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/vercel.json): deploy config · Deployment configuration for hosting integration · `vercel.json`
- [Deploy docs](https://github.com/raul-akhuli/menstral-health-detection-system/blob/main/DEPLOYMENT.md): documentation · Operational and integration notes for deployment · `DEPLOYMENT.md`

## Connections

- 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
