# alexxdceni/ml architecture

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

- Interactive diagram: https://gitdiagram.com/alexxdceni/ml
- Repository: https://github.com/alexxdceni/ml

## Overview

This repository is a from-scratch C++ neural-network framework with a task-selecting executable. The main workflow selects a task, loads a model and training or evaluation data, then trains or predicts; models can be saved, and MNIST and interactive point/function experiments are additional capabilities. The graph separates task orchestration, network computation and persistence, data utilities, and experiments. Edges reflect calls or references shown in excerpts, the source index, or the README; several internals are unsampled, so their relationships are omitted.

Main entry points: [`src/main.cpp`](https://github.com/alexxdceni/ml/blob/main/src/main.cpp) (Task runner), [`src/include/neural_network.hpp`](https://github.com/alexxdceni/ml/blob/main/src/include/neural_network.hpp) (Network engine), [`src/include/utils/mnist_util.hpp`](https://github.com/alexxdceni/ml/blob/main/src/include/utils/mnist_util.hpp) (MNIST utilities), [`src/include/utils/nn_signal_handler_util.hpp`](https://github.com/alexxdceni/ml/blob/main/src/include/utils/nn_signal_handler_util.hpp) (Interrupt autosave)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application workflow"]
  node_main["Task runner<br/>[main.cpp]"]
  node_signal["Interrupt autosave"]
end

subgraph group_network["Neural network"]
  node_nn["Network engine<br/>[neural_network.hpp]"]
  node_modelstore[("Saved models")]
  node_json["JSON support<br/>[json.hpp]"]
  node_legacy["Earlier network version"]
end

subgraph group_data["Data handling"]
  node_mnist["MNIST utilities<br/>[mnist_util.hpp]"]
  node_mnistdata[("MNIST files")]
  node_iofiles["Input and targets"]
end

subgraph group_experiments["Experiments and conversion"]
  node_converter["Image conversion<br/>[file_convertor.hpp]"]
  node_stb["Image decoder<br/>[stb_image.h]"]
  node_visual["Point and function tasks<br/>[functions_util.hpp]"]
end

node_user(("Task selector"))

node_user -->|"selects task"| node_main
node_main -->|"trains or predicts"| node_nn
node_main -->|"registers handler"| node_signal
node_main -->|"loads or tests MNIST"| node_mnist
node_main -->|"runs experiments"| node_visual
node_main -->|"loads task data"| node_iofiles
node_signal -->|"saves on interrupt"| node_modelstore
node_nn -->|"loads and saves"| node_modelstore
node_nn -->|"uses JSON configuration"| node_json
node_mnist -->|"fills training data"| node_nn
node_mnist -->|"reads dataset"| node_mnistdata
node_mnist -->|"uses image utilities"| node_converter
node_converter -->|"uses image decoder"| node_stb
node_visual -->|"trains and predicts"| node_nn

click node_main "https://github.com/alexxdceni/ml/blob/main/src/main.cpp"
click node_nn "https://github.com/alexxdceni/ml/blob/main/src/include/neural_network.hpp"
click node_modelstore "https://github.com/alexxdceni/ml/tree/main/models"
click node_json "https://github.com/alexxdceni/ml/blob/main/src/include/external/json.hpp"
click node_signal "https://github.com/alexxdceni/ml/blob/main/src/include/utils/nn_signal_handler_util.hpp"
click node_mnist "https://github.com/alexxdceni/ml/blob/main/src/include/utils/mnist_util.hpp"
click node_mnistdata "https://github.com/alexxdceni/ml/tree/main/data/mnist"
click node_iofiles "https://github.com/alexxdceni/ml/tree/main/data/io"
click node_converter "https://github.com/alexxdceni/ml/blob/main/src/include/utils/file_convertor.hpp"
click node_stb "https://github.com/alexxdceni/ml/blob/main/src/include/external/stb_image.h"
click node_visual "https://github.com/alexxdceni/ml/blob/main/src/include/utils/functions_util.hpp"
click node_legacy "https://github.com/alexxdceni/ml/blob/main/src/include/utils/v0-neural-network.hpp"

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_main,node_signal toneBlue
class node_nn,node_modelstore,node_json,node_legacy toneAmber
class node_mnist,node_mnistdata,node_iofiles toneMint
class node_converter,node_stb,node_visual,node_user toneRose
```

## Components

### Application workflow

- [Task runner](https://github.com/alexxdceni/ml/blob/main/src/main.cpp): `src/main.cpp`
- [Interrupt autosave](https://github.com/alexxdceni/ml/blob/main/src/include/utils/nn_signal_handler_util.hpp): `src/include/utils/nn_signal_handler_util.hpp`

### Neural network

- [Network engine](https://github.com/alexxdceni/ml/blob/main/src/include/neural_network.hpp): `src/include/neural_network.hpp`
- [Saved models](https://github.com/alexxdceni/ml/tree/main/models): `models`
- [JSON support](https://github.com/alexxdceni/ml/blob/main/src/include/external/json.hpp): `src/include/external/json.hpp`
- [Earlier network version](https://github.com/alexxdceni/ml/blob/main/src/include/utils/v0-neural-network.hpp): `src/include/utils/v0-neural-network.hpp`

### Data handling

- [MNIST utilities](https://github.com/alexxdceni/ml/blob/main/src/include/utils/mnist_util.hpp): `src/include/utils/mnist_util.hpp`
- [MNIST files](https://github.com/alexxdceni/ml/tree/main/data/mnist): `data/mnist`
- [Input and targets](https://github.com/alexxdceni/ml/tree/main/data/io): `data/io`

### Experiments and conversion

- [Image conversion](https://github.com/alexxdceni/ml/blob/main/src/include/utils/file_convertor.hpp): `src/include/utils/file_convertor.hpp`
- [Image decoder](https://github.com/alexxdceni/ml/blob/main/src/include/external/stb_image.h): `src/include/external/stb_image.h`
- [Point and function tasks](https://github.com/alexxdceni/ml/blob/main/src/include/utils/functions_util.hpp): `src/include/utils/functions_util.hpp`

### Other components

- **Task selector**

## Connections

- Task selector → Task runner: selects task (evidence: `src/main.cpp`)
- Task runner → Network engine: trains or predicts (evidence: `src/main.cpp`)
- Task runner → Interrupt autosave: registers handler (evidence: `src/main.cpp`)
- Task runner → MNIST utilities: loads or tests MNIST (evidence: `src/main.cpp`)
- Task runner → Point and function tasks: runs experiments (evidence: `src/main.cpp`)
- Task runner → Input and targets: loads task data (evidence: `src/main.cpp`)
- Interrupt autosave → Saved models: saves on interrupt (evidence: `src/include/utils/nn_signal_handler_util.hpp`)
- Network engine → Saved models: loads and saves (evidence: `src/include/neural_network.hpp`)
- Network engine → JSON support: uses JSON configuration (evidence: `src/include/neural_network.hpp`)
- MNIST utilities → Network engine: fills training data (evidence: `src/include/utils/mnist_util.hpp`)
- MNIST utilities → MNIST files: reads dataset (evidence: `src/include/utils/mnist_util.hpp`)
- MNIST utilities → Image conversion: uses image utilities (evidence: `src/include/utils/mnist_util.hpp`)
- Image conversion → Image decoder: uses image decoder (evidence: `src/include/utils/file_convertor.hpp`)
- Point and function tasks → Network engine: trains and predicts (evidence: `src/include/utils/functions_util.hpp`)
