# aaditya025/mlops_heart_disease_project architecture

> Architecture diagram of the GitHub repository aaditya025/mlops_heart_disease_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaditya025/mlops_heart_disease_project
- Repository: https://github.com/aaditya025/mlops_heart_disease_project

## Overview

1. This repository is organized around two clear planes: an offline ML lifecycle and an online inference/ops stack. The offline side prepares data, trains models, and stores artifacts; the online side serves predictions, exposes metrics, and supports deployment/monitoring.

2. The dataset lives in `data/` and is based on the UCI Heart Disease set. The repo includes raw and processed CSV-like files, plus a cleaned `heart_disease.csv`, so the training flow is file-based rather than database-backed.

3. The offline pipeline is implemented in `src/download_data.py`, `src/eda.py`, and `src/train.py`. The flow is: fetch/prepare data → perform EDA → train candidate classifiers → evaluate metrics → persist the chosen model artifacts.

4. Training is tracked with MLflow, which is materialized in the `mlruns/` directory. Each run stores parameters, metrics, and serialized model artifacts, making experiment comparison and reproducibility part of the architecture rather than an external concern.

5. The production model artifacts are also checked into `models/` as `best_model.pkl`, `pipeline.pkl`, `scaler.pkl`, and `feature_names.pkl`. This indicates the serving layer depends on prebuilt serialized artifacts, not live model training.

6. The serving boundary is `src/app.py`, a FastAPI application. It exposes `/predict`, `/health`, `/metrics`, `/model/info`, and documentation endpoints, and likely loads the trained pipeline at startup to transform input clinical features into a prediction response.

7. The repository also includes a small static frontend under `src/static/` (`index.html`, `script.js`, `style.css`), which acts as a lightweight UI for entering patient features and calling the prediction API. This UI sits beside, not inside, the model logic.

8. Observability is built into the service through Prometheus metrics and Grafana dashboards. `config/prometheus.yml` defines scraping, while `config/grafana/` contains datasource and dashboard provisioning plus a `model_metrics.json` dashboard definition. This means monitoring is intended to be fully provisioned from config.

9. A traffic generator (`generate_traffic.py`) and `traffic.log` suggest the system can simulate prediction load for testing the metrics pipeline and dashboard behavior. This matters because monitoring is part of the deliverable, not just the application.

10. Containerization is a first-class boundary. The `Dockerfile` packages the service, `docker-compose.yaml` assembles the local stack, and `start.sh` is the convenience entry point mentioned in the README for bringing up API + Prometheus + Grafana + traffic generation together.

11. Kubernetes deployment is defined separately in `k8s/deployment.yaml`, `k8s/ingress.yaml`, and `k8s/monitoring.yaml`. That split implies three deployment concerns: app pods, external access routing, and observability resources.

12. CI/CD is handled by GitHub Actions in `.github/workflows/ci-cd.yml`. The pipeline gates the repo with linting, tests, training, Docker build checks, security scanning, and deployment, so the software lifecycle is automated end-to-end.

13. Tests are split by concern in `tests/`: `test_data.py`, `test_model.py`, and `test_api.py`. That mirrors the architecture: data validation, model behavior, and service contract are verified independently.

14. There is no evidence of a backing database, queue, or external model server. The system’s core state is file-based: datasets, MLflow runs, and pickled artifacts on disk, which keeps the architecture simple but ties inference to packaged model files.

15. For diagramming, the key data flow is: dataset files → EDA/training → MLflow + serialized model artifacts → FastAPI inference service → Prometheus/Grafana monitoring. Deployment then wraps the same service in Docker and Kubernetes.

Main entry points: [`src/app.py`](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/app.py) (FastAPI app), [`src/train.py`](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/train.py) (Train model), [`.github/workflows/ci-cd.yml`](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/.github/workflows/ci-cd.yml) (CI/CD), [`config/prometheus.yml`](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/prometheus.yml) (Prometheus cfg)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline ML"]
  node_data_repo["Heart data<br/>dataset files<br/>[heart_disease.csv]"]
  node_data_prep["Fetch data<br/>prep script<br/>[download_data.py]"]
  node_eda["EDA<br/>analysis script<br/>[eda.py]"]
  node_train["Train model<br/>training script<br/>[train.py]"]
  node_mlflow[("MLflow runs<br/>experiment store<br/>[meta.yaml]")]
  node_artifact_store[("Model files<br/>serialized artifacts<br/>[pipeline.pkl]")]
end

subgraph group_online["Online Serving"]
  node_api["FastAPI app<br/>serving service<br/>[app.py]"]
  node_ui["Static UI<br/>frontend assets<br/>[index.html]"]
  node_predict_flow{{"Inference path<br/>runtime flow"}}
end

subgraph group_ops["Ops & Deploy"]
  node_prometheus_cfg["Prometheus cfg<br/>monitoring config<br/>[prometheus.yml]"]
  node_grafana_cfg["Grafana cfg<br/>dashboard provisioning<br/>[dashboard.yml]"]
  node_dashboard["Metrics dashboard<br/>grafana dashboard<br/>[model_metrics.json]"]
  node_traffic["Load generator<br/>traffic script"]
  node_compose["Compose stack<br/>local orchestration"]
  node_dockerfile["Service image<br/>container build"]
  node_k8s_app["App deploy<br/>k8s manifest<br/>[deployment.yaml]"]
  node_k8s_route["Ingress<br/>k8s manifest<br/>[ingress.yaml]"]
  node_k8s_obs["K8s monitoring<br/>k8s manifest<br/>[monitoring.yaml]"]
end

subgraph group_qa["Quality"]
  node_ci_cd["CI/CD<br/>workflow<br/>[ci-cd.yml]"]
  node_tests["Tests<br/>test suite<br/>[test_api.py]"]
end

node_data_repo -->|"source data"| node_data_prep
node_data_prep -->|"prepared data"| node_eda
node_eda -->|"insights"| node_train
node_data_repo -->|"training set"| node_train
node_train -->|"log runs"| node_mlflow
node_train -->|"persist model"| node_artifact_store
node_mlflow -->|"best artifacts"| node_artifact_store
node_artifact_store -->|"load model"| node_api
node_api -->|"serve predictions"| node_predict_flow
node_ui -->|"call predict"| node_api
node_api -->|"emit metrics"| node_prometheus_cfg
node_prometheus_cfg -->|"scrape data"| node_dashboard
node_grafana_cfg -->|"provision"| node_dashboard
node_traffic -->|"load test"| node_api
node_compose -->|"orchestrate"| node_api
node_compose -->|"orchestrate"| node_prometheus_cfg
node_compose -->|"orchestrate"| node_grafana_cfg
node_dockerfile -->|"package"| node_api
node_k8s_app -->|"deploy"| node_api
node_k8s_route -->|"route"| node_api
node_k8s_obs -->|"monitor"| node_prometheus_cfg
node_ci_cd -->|"run tests"| node_tests
node_ci_cd -->|"train check"| node_train
node_ci_cd -->|"build image"| node_dockerfile
node_ci_cd -->|"deploy check"| node_k8s_app

click node_data_repo "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/data/heart_disease.csv"
click node_data_prep "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/download_data.py"
click node_eda "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/eda.py"
click node_train "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/train.py"
click node_mlflow "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/mlruns/551504309071015152/meta.yaml"
click node_artifact_store "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/models/pipeline.pkl"
click node_api "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/app.py"
click node_ui "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/static/index.html"
click node_prometheus_cfg "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/prometheus.yml"
click node_grafana_cfg "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/grafana/provisioning/dashboards/dashboard.yml"
click node_dashboard "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/grafana/dashboards/model_metrics.json"
click node_traffic "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/generate_traffic.py"
click node_compose "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/docker-compose.yaml"
click node_dockerfile "https://github.com/aaditya025/mlops_heart_disease_project/tree/main/Dockerfile"
click node_k8s_app "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/deployment.yaml"
click node_k8s_route "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/ingress.yaml"
click node_k8s_obs "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/monitoring.yaml"
click node_ci_cd "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/.github/workflows/ci-cd.yml"
click node_tests "https://github.com/aaditya025/mlops_heart_disease_project/blob/main/tests/test_api.py"

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_data_repo,node_data_prep,node_eda,node_train,node_mlflow,node_artifact_store toneBlue
class node_api,node_ui,node_predict_flow toneAmber
class node_prometheus_cfg,node_grafana_cfg,node_dashboard,node_traffic,node_compose,node_dockerfile,node_k8s_app,node_k8s_route,node_k8s_obs toneMint
class node_ci_cd,node_tests toneRose
```

## Components

### Offline ML

Data prep, EDA, training, and experiment tracking

- [Heart data](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/data/heart_disease.csv): dataset files · UCI Heart Disease CSV-style inputs and cleaned dataset · `data/heart_disease.csv`
- [Fetch data](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/download_data.py): prep script · Downloads or prepares the source heart disease data · `src/download_data.py`
- [EDA](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/eda.py): analysis script · Explores and summarizes the dataset before training · `src/eda.py`
- [Train model](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/train.py): training script · Builds candidate classifiers and evaluates metrics · `src/train.py`
- [MLflow runs](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/mlruns/551504309071015152/meta.yaml): experiment store · Tracks parameters, metrics, and serialized model artifacts · `mlruns/551504309071015152/meta.yaml`
- [Model files](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/models/pipeline.pkl): serialized artifacts · Checked-in pipeline, scaler, feature names, and best model · `models/pipeline.pkl`

### Online Serving

API, UI, and prediction runtime

- [FastAPI app](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/app.py): serving service · Prediction API with health, metrics, and model info endpoints · `src/app.py`
- [Static UI](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/src/static/index.html): frontend assets · Simple browser interface for entering patient features and calling the API · `src/static/index.html`
- **Inference path**: runtime flow · Loads the packaged pipeline and transforms inputs into predictions

### Ops & Deploy

Monitoring, traffic generation, containers, and cluster deployment

- [Prometheus cfg](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/prometheus.yml): monitoring config · Scrape configuration for service metrics collection · `config/prometheus.yml`
- [Grafana cfg](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/grafana/provisioning/dashboards/dashboard.yml): dashboard provisioning · Datasource and dashboard provisioning for monitoring · `config/grafana/provisioning/dashboards/dashboard.yml`
- [Metrics dashboard](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/config/grafana/dashboards/model_metrics.json): grafana dashboard · Model and service metrics visualization · `config/grafana/dashboards/model_metrics.json`
- [Load generator](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/generate_traffic.py): traffic script · Simulates prediction traffic to exercise monitoring · `generate_traffic.py`
- [Compose stack](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/docker-compose.yaml): local orchestration · Brings up API, monitoring, and optional traffic together · `docker-compose.yaml`
- [Service image](https://github.com/aaditya025/mlops_heart_disease_project/tree/main/Dockerfile): container build · Packages the API for container deployment · `Dockerfile`
- [App deploy](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/deployment.yaml): k8s manifest · Kubernetes deployment for the service pods · `k8s/deployment.yaml`
- [Ingress](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/ingress.yaml): k8s manifest · External routing into the service · `k8s/ingress.yaml`
- [K8s monitoring](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/k8s/monitoring.yaml): k8s manifest · Cluster-side observability resources · `k8s/monitoring.yaml`

### Quality

Automated checks around data, model, and API

- [CI/CD](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/.github/workflows/ci-cd.yml): workflow · Automated lint, test, train, build, scan, and deploy pipeline · `.github/workflows/ci-cd.yml`
- [Tests](https://github.com/aaditya025/mlops_heart_disease_project/blob/main/tests/test_api.py): test suite · Checks data handling, model behavior, and API contract · `tests/test_api.py`

## Connections

- Heart data → Fetch data: source data · Raw and cleaned files feed preparation
- Fetch data → EDA: prepared data · Prepared dataset is inspected in EDA
- EDA → Train model: insights · Exploration informs training and feature handling
- Heart data → Train model: training set · Training consumes the file-based heart disease dataset
- Train model → MLflow runs: log runs · Metrics, params, and artifacts are recorded in MLflow
- Train model → Model files: persist model · Chosen model artifacts are stored for serving
- MLflow runs → Model files: best artifacts · Registered model outputs mirror the packaged artifacts
- Model files → FastAPI app: load model · FastAPI loads the serialized pipeline and auxiliaries
- FastAPI app → Inference path: serve predictions · Request handling enters the inference path
- Static UI → FastAPI app: call predict · Frontend submits feature payloads to the API
- FastAPI app → Prometheus cfg: emit metrics · Service exposes metrics for scraping
- Prometheus cfg → Metrics dashboard: scrape data · Prometheus feeds monitoring dashboards
- Grafana cfg → Metrics dashboard: provision · Dashboards and datasource are provisioned from config
- Load generator → FastAPI app: load test · Synthetic traffic drives prediction and metrics activity
- Compose stack → FastAPI app: orchestrate · Compose starts the service container
- Compose stack → Prometheus cfg: orchestrate · Compose also brings up monitoring components
- Compose stack → Grafana cfg: orchestrate · Grafana is part of the local stack
- Service image → FastAPI app: package · The API is containerized from the project image
- App deploy → FastAPI app: deploy · Kubernetes deployment runs the service
- Ingress → FastAPI app: route · Ingress exposes the service externally
- K8s monitoring → Prometheus cfg: monitor · Cluster monitoring aligns with Prometheus scraping
- CI/CD → Tests: run tests · Pipeline executes automated validation
- CI/CD → Train model: train check · Pipeline includes training-related verification
- CI/CD → Service image: build image · Pipeline validates container build
- CI/CD → App deploy: deploy check · Pipeline covers deployment artifacts
