# mobeen-dev/ml-algorithms-testing architecture

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

- Interactive diagram: https://gitdiagram.com/mobeen-dev/ml-algorithms-testing
- Repository: https://github.com/mobeen-dev/ml-algorithms-testing

## Overview

1. This repository is a small machine-learning project organized around a “from scratch” implementation boundary: all model logic lives under `src/`, while top-level scripts handle dataset generation, experiments, visualization, and report building.

2. The core algorithms are split into three independent model modules:
   - `src/kmeans.py` for k-Means clustering
   - `src/gnb.py` for Gaussian Naive Bayes
   - `src/c45_tree.py` for a Decision Tree using C4.5-style gain ratio with binary splits  
   This makes the `src/` directory the main algorithm layer of the repo.

3. `src/utils.py` is the shared support layer. It likely contains reusable helpers for preprocessing, metrics, split logic, or array/dataframe utilities used by multiple models, keeping the model modules thinner and avoiding duplicated logic.

4. `src/viz.py` is the presentation/analysis layer for plots. The README says plots are saved to `report_assets/`, so the visualization module is the bridge from experiment outputs to report-ready figures.

5. `dataset_generator.py` is the data-production entrypoint. The README states datasets are generated programmatically with seed `050`, so the project is not depending on an external dataset file; instead, the data pipeline begins with reproducible synthetic generation.

6. `experiments.py` is the orchestration layer. It appears to run the full benchmark suite (`python experiments.py --all`), invoking dataset generation, training/evaluating the three models, and producing outputs for the report and plot assets.

7. `build_report_pdf.py` is the report compilation step. The presence of `report.md`, `report_template.md`, and `report.pdf` suggests a markdown-to-PDF workflow, with the build script converting the authored report into the final PDF artifact.

8. `report.md` is the human-readable experiment writeup, while `report_template.md` is the source template used to generate or format that report. `report_assets/` holds generated figures referenced by the report.

9. `requirements.txt` shows the runtime dependency boundary: the implementation is constrained to NumPy, Pandas, and Matplotlib, with no sklearn model APIs. That constraint is central to the architecture because it forces all learning logic into the repository’s own `src/` modules.

10. The repo also contains packaged deliverables under `submission_bundle/` and `submission_bundle_065/`, plus corresponding zip archives. These are duplicate frozen snapshots of the code/report used for submission or grading, separate from the main working copy.

11. From an architecture diagram perspective, the main data flow is: synthetic dataset generation → model training/evaluation in `experiments.py` using the `src/` implementations → plots in `report_assets/` via `src/viz.py` → narrative/report assembly in `report.md`/`report.pdf`.

12. The main boundary to preserve in a diagram is between “orchestration/reporting scripts” and “pure model implementations.” The top-level scripts coordinate the workflow, but the actual ML behavior is encapsulated in the three algorithm modules under `src/`.

Main entry points: [`experiments.py`](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/experiments.py) (Experiments), [`src/__init__.py`](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/__init__.py) (src package), [`requirements.txt`](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/requirements.txt) (Deps), [`report.md`](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report.md) (Report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow"]
  node_dataset_generator_py["Dataset gen<br/>entry script"]
  node_experiments_py["Experiments<br/>orchestrator<br/>[experiments.py]"]
  node_build_report_pdf_py["Build PDF<br/>report builder"]
end

subgraph group_models["Models"]
  node_src_utils_py["Utils<br/>shared helpers<br/>[utils.py]"]
  node_src_kmeans_py["k-Means<br/>clustering model<br/>[kmeans.py]"]
  node_src_gnb_py["Naive Bayes<br/>classifier<br/>[gnb.py]"]
  node_src_c45_tree_py["C4.5 tree<br/>decision tree<br/>[c45_tree.py]"]
  node_src_viz_py["Visuals<br/>plotting<br/>[viz.py]"]
  node_src_init_py["src package<br/>[__init__.py]"]
end

subgraph group_deliverables["Deliverables"]
  node_report_md["Report<br/>writeup<br/>[report.md]"]
  node_report_template_md["Template<br/>[report_template.md]"]
  node_report_pdf["PDF<br/>final artifact<br/>[report.pdf]"]
  node_report_assets[("Assets<br/>figure output")]
  node_requirements_txt["Deps<br/>runtime constraints<br/>[requirements.txt]"]
end

subgraph group_snapshots["Snapshots"]
  node_submission_bundle["Bundle<br/>submission snapshot"]
  node_submission_bundle_065["Bundle 065<br/>submission snapshot"]
  node_submission_bundle_seed050_zip["Zip 050<br/>archive"]
  node_submission_bundle_seed065_zip["Zip 065<br/>archive"]
end

node_experiments_py -->|"generate data"| node_dataset_generator_py
node_experiments_py -->|"run"| node_src_kmeans_py
node_experiments_py -->|"run"| node_src_gnb_py
node_experiments_py -->|"run"| node_src_c45_tree_py
node_experiments_py -->|"share helpers"| node_src_utils_py
node_experiments_py -->|"plot results"| node_src_viz_py
node_src_viz_py -->|"save figures"| node_report_assets
node_experiments_py -->|"feed results"| node_report_md
node_report_template_md -->|"format"| node_report_md
node_report_md -->|"compile"| node_build_report_pdf_py
node_build_report_pdf_py -->|"emit"| node_report_pdf
node_report_md -->|"reference"| node_report_assets
node_src_init_py -->|"package"| node_src_kmeans_py
node_src_init_py -->|"package"| node_src_gnb_py
node_src_init_py -->|"package"| node_src_c45_tree_py
node_src_init_py -->|"package"| node_src_utils_py
node_src_init_py -->|"package"| node_src_viz_py
node_requirements_txt -.->|"constrain"| node_experiments_py
node_requirements_txt -.->|"constrain"| node_src_kmeans_py
node_requirements_txt -.->|"constrain"| node_src_gnb_py
node_requirements_txt -.->|"constrain"| node_src_c45_tree_py
node_submission_bundle -->|"package"| node_submission_bundle_seed050_zip
node_submission_bundle_065 -->|"package"| node_submission_bundle_seed065_zip
node_submission_bundle -.->|"contains"| node_report_pdf
node_submission_bundle_065 -.->|"contains"| node_report_pdf

click node_dataset_generator_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/dataset_generator.py"
click node_experiments_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/experiments.py"
click node_build_report_pdf_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/build_report_pdf.py"
click node_src_utils_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/utils.py"
click node_src_kmeans_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/kmeans.py"
click node_src_gnb_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/gnb.py"
click node_src_c45_tree_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/c45_tree.py"
click node_src_viz_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/viz.py"
click node_src_init_py "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/__init__.py"
click node_report_md "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report.md"
click node_report_template_md "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report_template.md"
click node_report_pdf "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report.pdf"
click node_report_assets "https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/report_assets"
click node_submission_bundle "https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/submission_bundle"
click node_submission_bundle_065 "https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/submission_bundle_065"
click node_submission_bundle_seed050_zip "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/submission_bundle_seed050.zip"
click node_submission_bundle_seed065_zip "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/submission_bundle_seed065.zip"
click node_requirements_txt "https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/requirements.txt"

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_dataset_generator_py,node_experiments_py,node_build_report_pdf_py toneBlue
class node_src_utils_py,node_src_kmeans_py,node_src_gnb_py,node_src_c45_tree_py,node_src_viz_py,node_src_init_py toneAmber
class node_report_md,node_report_template_md,node_report_pdf,node_report_assets,node_requirements_txt toneMint
class node_submission_bundle,node_submission_bundle_065,node_submission_bundle_seed050_zip,node_submission_bundle_seed065_zip toneRose
```

## Components

### Workflow

Top-level scripts that generate data, run experiments, and build the final report.

- [Dataset gen](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/dataset_generator.py): entry script · Reproducible synthetic dataset creation entrypoint. · `dataset_generator.py`
- [Experiments](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/experiments.py): orchestrator · Runs the benchmark suite and coordinates model evaluation. · `experiments.py`
- [Build PDF](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/build_report_pdf.py): report builder · Converts the authored report into the final PDF artifact. · `build_report_pdf.py`

### Models

Core from-scratch algorithm implementations under src/.

- [Utils](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/utils.py): shared helpers · Reusable support code shared across model modules. · `src/utils.py`
- [k-Means](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/kmeans.py): clustering model · From-scratch k-Means implementation. · `src/kmeans.py`
- [Naive Bayes](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/gnb.py): classifier · Gaussian Naive Bayes implementation. · `src/gnb.py`
- [C4.5 tree](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/c45_tree.py): decision tree · Decision tree with gain ratio and binary splits. · `src/c45_tree.py`
- [Visuals](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/viz.py): plotting · Produces report-ready figures from experiment outputs. · `src/viz.py`
- [src package](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/src/__init__.py): package · Package boundary for the model implementation layer. · `src/__init__.py`

### Deliverables

Report files and generated assets consumed by the writeup pipeline.

- [Report](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report.md): writeup · Human-readable experiment narrative and results. · `report.md`
- [Template](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report_template.md): report template · Markdown template used to format or generate the report. · `report_template.md`
- [PDF](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/report.pdf): final artifact · Compiled final report deliverable. · `report.pdf`
- [Assets](https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/report_assets): figure output · Generated plots and images referenced by the report. · `report_assets`
- [Deps](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/requirements.txt): runtime constraints · Dependency boundary for the project runtime. · `requirements.txt`

### Snapshots

Frozen submission bundles and archive artifacts.

- [Bundle](https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/submission_bundle): submission snapshot · Frozen submission copy of the project. · `submission_bundle`
- [Bundle 065](https://github.com/mobeen-dev/ml-algorithms-testing/tree/main/submission_bundle_065): submission snapshot · Second frozen submission copy of the project. · `submission_bundle_065`
- [Zip 050](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/submission_bundle_seed050.zip): archive · Packaged submission archive for seed 050. · `submission_bundle_seed050.zip`
- [Zip 065](https://github.com/mobeen-dev/ml-algorithms-testing/blob/main/submission_bundle_seed065.zip): archive · Packaged submission archive for seed 065. · `submission_bundle_seed065.zip`

## Connections

- Experiments → Dataset gen: generate data · Experiments begin by producing the synthetic dataset.
- Experiments → k-Means: run · Benchmark orchestration invokes k-Means.
- Experiments → Naive Bayes: run · Benchmark orchestration invokes Gaussian Naive Bayes.
- Experiments → C4.5 tree: run · Benchmark orchestration invokes the decision tree.
- Experiments → Utils: share helpers · Models reuse common utilities during evaluation.
- Experiments → Visuals: plot results · Experiment outputs are turned into figures.
- Visuals → Assets: save figures · Plots are written into the report assets directory.
- Experiments → Report: feed results · Experiment outputs populate the narrative report.
- Template → Report: format · Template provides the report structure.
- Report → Build PDF: compile · The authored markdown is compiled into PDF.
- Build PDF → PDF: emit · Build step produces the final PDF artifact.
- Report → Assets: reference · The report includes generated figures from the assets folder.
- src package → k-Means: package · Package boundary includes the clustering module.
- src package → Naive Bayes: package · Package boundary includes the Naive Bayes module.
- src package → C4.5 tree: package · Package boundary includes the decision tree module.
- src package → Utils: package · Package boundary includes shared utilities.
- src package → Visuals: package · Package boundary includes plotting support.
- Deps → Experiments: constrain · Runtime dependencies constrain the orchestration layer.
- Deps → k-Means: constrain · Runtime dependencies constrain the algorithm implementation.
- Deps → Naive Bayes: constrain · Runtime dependencies constrain the algorithm implementation.
- Deps → C4.5 tree: constrain · Runtime dependencies constrain the algorithm implementation.
- Bundle → Zip 050: package · Submission bundle is mirrored by the archived zip.
- Bundle 065 → Zip 065: package · Second bundle is mirrored by its archived zip.
- Bundle → PDF: contains · Frozen bundle carries the report deliverable.
- Bundle 065 → PDF: contains · Frozen bundle carries the report deliverable.
