# vitthalhumbe/myalgo architecture

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

- Interactive diagram: https://gitdiagram.com/vitthalhumbe/myalgo
- Repository: https://github.com/vitthalhumbe/myalgo

## Overview

1. **Overall shape**
   - This is a Python package named `myalgo` that implements two machine-learning algorithms from scratch: **Linear Regression** and a **feed-forward Artificial Neural Network**.
   - The repo is organized as a layered system: a **Python-facing API** on top, a **C++ numerical backend** underneath, and **tests/CI/release tooling** around it.

2. **Public package boundary**
   - The installable code lives under `src/myalgo`, which is the main package boundary.
   - `src/myalgo/__init__.py` exposes the package namespace, while the algorithm entry points are split into `linear_regression.py` and `ann.py`.

3. **Linear Regression subsystem**
   - `src/myalgo/linear_regression.py` is the user-facing implementation for regression.
   - The README indicates it supports multiple training methods: **Normal Equation**, **Gradient Descent**, and **Stochastic Gradient Descent**, plus regularization modes: **Lasso**, **Ridge**, and **Elastic Net**.
   - This module is the main orchestration layer for model fitting, prediction, and configuration.

4. **ANN subsystem**
   - `src/myalgo/ann.py` is the high-level neural network module.
   - The README shows a compositional model API built from layer objects such as `Flatten` and `Dense`, with activations like **ReLU**, **sigmoid**, **tanh**, and **softmax**.
   - It also manages training concerns such as loss selection, learning rate, epochs, and batch size.

5. **Neural-network building blocks**
   - `src/myalgo/neuron.py` suggests a lower-level implementation of neuron/layer primitives used by the ANN stack.
   - Architecturally, this sits between the high-level network API and the numerical backend, likely encapsulating forward/backward behavior for dense computation.

6. **C++ performance backend**
   - The directory `src/myalgo/_cpp` contains `ann.cpp` and `linear_regression.cpp`.
   - This is the computational core for numeric-heavy work, and the README explicitly says C++ is used as the high-performance backend for numerical calculations.
   - The architecture boundary is clear: **Python manages API and model flow; C++ handles performance-sensitive math**.

7. **Python-to-native integration**
   - The repo is packaged with `setup.py` and `pyproject.toml`, which indicates the build/install path is likely responsible for compiling and exposing the C++ code as part of the Python package.
   - For an architecture diagram, it is important to show this as a cross-language boundary between the Python modules and the compiled backend.

8. **Training and inference data flow**
   - Typical flow for both algorithms is: user code imports `myalgo`, constructs a model, calls `fit`/`train`, and then calls `predict`.
   - For ANN, data flows through layer composition, activation/loss evaluation, and iterative optimization.
   - For linear regression, data flows through the chosen optimization method or closed-form solution, then into prediction.

9. **Test coverage boundary**
   - `tests/test_linear_regression.py` and `tests/test_ann.py` provide algorithm-level verification.
   - These tests imply the repo validates both the public API and the core model behavior, likely covering training and prediction paths.

10. **Documentation and examples**
   - `README.md` provides the primary usage documentation and feature summary.
   - `docs/MyAlgo.pdf` appears to be the fuller project documentation, while `results/MNIST loss vs Accuracy.png` is a saved experiment artifact rather than runtime code.

11. **CI and release pipeline**
   - `.github/workflows/ci.yml` suggests automated testing/validation on changes.
   - `.github/workflows/publish.yml` suggests a release workflow for packaging and publishing the library, likely to PyPI given the README badge and install instructions.

12. **Key architectural boundaries to show in a diagram**
   - **User application boundary:** external Python code calling the package.
   - **Python API layer:** `ann.py`, `linear_regression.py`, `neuron.py`.
   - **Native compute boundary:** `src/myalgo/_cpp/*.cpp`.
   - **Quality/release boundary:** tests and GitHub Actions.
   - This separation is the most important structural feature of the repository.

13. **Notable implementation intent**
   - The project is intentionally “from scratch” and does not depend on high-level ML frameworks like TensorFlow, PyTorch, or scikit-learn.
   - That means the architecture is self-contained and centered on its own algorithm implementations rather than external ML services or frameworks.

Main entry points: [`src/myalgo/ann.py`](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/ann.py) (Neural network), [`setup.py`](https://github.com/vitthalhumbe/myalgo/blob/main/setup.py) (Build config), [`src/myalgo/linear_regression.py`](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/linear_regression.py) (Linear regression), [`src/myalgo/__init__.py`](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/__init__.py) (Package init)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Python API"]
  node_package_init["Package init<br/>package entry<br/>[__init__.py]"]
  node_linear_regression_api["Linear regression<br/>model API"]
  node_ann_api["Neural network<br/>model API<br/>[ann.py]"]
  node_neuron_core["Neuron core<br/>layer primitives<br/>[neuron.py]"]
end

subgraph group_native_backend["C++ backend"]
  node_cpp_ann["ANN compute<br/>native module<br/>[ann.cpp]"]
  node_cpp_lr["Regression compute<br/>native module"]
end

subgraph group_quality_release["Quality & release"]
  node_test_ann["ANN tests<br/>[test_ann.py]"]
  node_test_lr["Regression tests"]
  node_ci_workflow["CI workflow<br/>automation<br/>[ci.yml]"]
  node_publish_workflow["Publish workflow<br/>automation<br/>[publish.yml]"]
end

subgraph group_docs_assets["Docs & assets"]
  node_readme["README<br/>documentation<br/>[README.md]"]
  node_project_docs["Project docs<br/>documentation<br/>[MyAlgo.pdf]"]
  node_experiment_artifact["Experiment plot<br/>artifact"]
end

node_external_user(("User code<br/>consumer"))
node_build_config["Build config<br/>packaging<br/>[setup.py]"]
node_project_meta["Project meta<br/>packaging<br/>[pyproject.toml]"]

node_external_user -->|"imports"| node_package_init
node_package_init -->|"exposes"| node_linear_regression_api
node_package_init -->|"exposes"| node_ann_api
node_linear_regression_api -->|"uses"| node_cpp_lr
node_ann_api -->|"composes"| node_neuron_core
node_ann_api -->|"uses"| node_cpp_ann
node_neuron_core -->|"bridges"| node_cpp_ann
node_build_config -->|"builds"| node_cpp_ann
node_build_config -->|"builds"| node_cpp_lr
node_project_meta -.->|"describes"| node_build_config
node_test_ann -->|"verifies"| node_ann_api
node_test_lr -->|"verifies"| node_linear_regression_api
node_ci_workflow -->|"runs"| node_test_ann
node_ci_workflow -->|"runs"| node_test_lr
node_publish_workflow -->|"packages"| node_build_config
node_readme -.->|"documents"| node_linear_regression_api
node_readme -.->|"documents"| node_ann_api
node_project_docs -.->|"extends"| node_readme

click node_package_init "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/__init__.py"
click node_linear_regression_api "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/linear_regression.py"
click node_ann_api "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/ann.py"
click node_neuron_core "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/neuron.py"
click node_cpp_ann "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/_cpp/ann.cpp"
click node_cpp_lr "https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/_cpp/linear_regression.cpp"
click node_build_config "https://github.com/vitthalhumbe/myalgo/blob/main/setup.py"
click node_project_meta "https://github.com/vitthalhumbe/myalgo/blob/main/pyproject.toml"
click node_test_ann "https://github.com/vitthalhumbe/myalgo/blob/main/tests/test_ann.py"
click node_test_lr "https://github.com/vitthalhumbe/myalgo/blob/main/tests/test_linear_regression.py"
click node_ci_workflow "https://github.com/vitthalhumbe/myalgo/blob/main/.github/workflows/ci.yml"
click node_publish_workflow "https://github.com/vitthalhumbe/myalgo/blob/main/.github/workflows/publish.yml"
click node_readme "https://github.com/vitthalhumbe/myalgo/blob/main/README.md"
click node_project_docs "https://github.com/vitthalhumbe/myalgo/blob/main/docs/MyAlgo.pdf"

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_package_init,node_linear_regression_api,node_ann_api,node_neuron_core toneBlue
class node_cpp_ann,node_cpp_lr toneAmber
class node_test_ann,node_test_lr,node_ci_workflow,node_publish_workflow toneMint
class node_readme,node_project_docs,node_experiment_artifact toneRose
class node_external_user,node_build_config,node_project_meta toneNeutral
```

## Components

### Python API

Installable package boundary and user-facing modules.

- [Package init](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/__init__.py): package entry · Exposes the myalgo namespace. · `src/myalgo/__init__.py`
- [Linear regression](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/linear_regression.py): model API · High-level regression training and prediction API. · `src/myalgo/linear_regression.py`
- [Neural network](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/ann.py): model API · High-level ANN construction and training API. · `src/myalgo/ann.py`
- [Neuron core](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/neuron.py): layer primitives · Lower-level neuron and layer behavior used by the ANN stack. · `src/myalgo/neuron.py`

### C++ backend

Performance-sensitive numerical core compiled into the package.

- [ANN compute](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/_cpp/ann.cpp): native module · C++ numerical backend for ANN operations. · `src/myalgo/_cpp/ann.cpp`
- [Regression compute](https://github.com/vitthalhumbe/myalgo/blob/main/src/myalgo/_cpp/linear_regression.cpp): native module · C++ numerical backend for linear regression operations. · `src/myalgo/_cpp/linear_regression.cpp`

### Quality & release

Tests and CI/release automation around the package.

- [ANN tests](https://github.com/vitthalhumbe/myalgo/blob/main/tests/test_ann.py): test · Algorithm-level verification for neural network behavior. · `tests/test_ann.py`
- [Regression tests](https://github.com/vitthalhumbe/myalgo/blob/main/tests/test_linear_regression.py): test · Algorithm-level verification for linear regression behavior. · `tests/test_linear_regression.py`
- [CI workflow](https://github.com/vitthalhumbe/myalgo/blob/main/.github/workflows/ci.yml): automation · Automated validation on changes. · `.github/workflows/ci.yml`
- [Publish workflow](https://github.com/vitthalhumbe/myalgo/blob/main/.github/workflows/publish.yml): automation · Release and publishing pipeline for packaged builds. · `.github/workflows/publish.yml`

### Docs & assets

Documentation and experiment artifacts.

- [README](https://github.com/vitthalhumbe/myalgo/blob/main/README.md): documentation · Primary usage guide and feature summary. · `README.md`
- [Project docs](https://github.com/vitthalhumbe/myalgo/blob/main/docs/MyAlgo.pdf): documentation · Full project documentation artifact. · `docs/MyAlgo.pdf`
- **Experiment plot**: artifact · Saved result from model experimentation.

### Other components

- **User code**: consumer · External Python application using the package.
- [Build config](https://github.com/vitthalhumbe/myalgo/blob/main/setup.py): packaging · Python packaging and native extension build entry points. · `setup.py`
- [Project meta](https://github.com/vitthalhumbe/myalgo/blob/main/pyproject.toml): packaging · Build system and project metadata. · `pyproject.toml`

## Connections

- User code → Package init: imports · User code imports the package namespace.
- Package init → Linear regression: exposes · Namespace surfaces regression API.
- Package init → Neural network: exposes · Namespace surfaces ANN API.
- Linear regression → Regression compute: uses · Regression delegates numerical work to C++ backend.
- Neural network → Neuron core: composes · ANN builds models from lower-level primitives.
- Neural network → ANN compute: uses · ANN delegates compute-heavy operations to C++ backend.
- Neuron core → ANN compute: bridges · Layer primitives sit between Python API and native compute.
- Build config → ANN compute: builds · Packaging compiles and exposes native ANN code.
- Build config → Regression compute: builds · Packaging compiles and exposes native regression code.
- Project meta → Build config: describes · Project metadata supports the build/install path.
- ANN tests → Neural network: verifies · Tests exercise ANN public behavior.
- Regression tests → Linear regression: verifies · Tests exercise regression public behavior.
- CI workflow → ANN tests: runs · CI executes ANN tests.
- CI workflow → Regression tests: runs · CI executes regression tests.
- Publish workflow → Build config: packages · Release workflow produces distributable builds.
- README → Linear regression: documents · README describes regression usage and options.
- README → Neural network: documents · README describes ANN layers and training.
- Project docs → README: extends · PDF documentation expands on the README.