# oularefodos/multi-layer-perceptron architecture

> Architecture diagram of the GitHub repository oularefodos/multi-layer-perceptron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oularefodos/multi-layer-perceptron
- Repository: https://github.com/oularefodos/multi-layer-perceptron

## Overview

##### Project type and purpose
- This is a machine-learning pipeline project implementing a Multilayer Perceptron (MLP) from scratch in Python, focused on binary classification (Wisconsin Breast Cancer Dataset).
- It provides a full pipeline: data ingestion, preprocessing (splitting), model training (feedforward + backpropagation), evaluation (learning curves), and prediction.

##### File structure
- Top-level artifacts:
- Makefile – orchestration of tasks (install, split, train, predict, clean)
- requirements.txt – Python dependencies
- data/ – raw and split dataset (data.csv etc.)
- src/ – core Python modules:
– Model.py – neural network architecture and forward/backward logic
– helpers.py – common utilities (e.g., metrics, plotting)
– split_dataset.py – data preprocessing & train/test split
– train.py – training loop and loss tracking
– predict.py – loading model and running inference
- No external APIs or services; everything runs locally via scripts invoked by Makefile.

##### README for additional insights
- Describes feedforward, backpropagation, modular layers, softmax, cross-entropy, learning-curve visualization.
- Usage driven by make targets that wire together the Python scripts and data.

a. Main components (suggest grouping into layers/modules):
1. Data Layer
- Raw Data (data/data.csv)
- Preprocessor (split_dataset.py)
2. Model Layer
- Neural Network Module (Model.py)
- Helper Utilities (helpers.py for loss, activation, plotting)
3. Pipeline Orchestration
- Makefile targets invoking the Python scripts in sequence
4. Execution Scripts
- train.py (trains the model, emits training curves, serializes model artifacts)
- predict.py (loads trained model, runs inference on test set)
5. Artifacts
- Trained model file(s)
- Learning curve plots
- Prediction outputs

b. Relationships and interactions
1. The Makefile orchestrates:
- install → split_dataset.py → train.py → predict.py
2. split_dataset.py reads data/data.csv, writes train/test sets into data/ subfolders
3. train.py imports Model.py and helpers.py; it consumes train set, produces a serialized model (e.g., .pkl), and generates loss/accuracy plots via helpers.py
4. predict.py loads the serialized model, runs forward passes on test set, outputs classification results

c. Architectural patterns and design principles
- Modular design: separation of concerns between data preprocessing, model definition, training loop, and prediction.
- Layered pipeline orchestrated by Makefile—each stage has its own script.
- Single-process, script-driven batch pipeline (no microservices, no web tier).

d. Key technologies and libraries
- Pure Python (no high-level ML frameworks)
- numpy (assumed for matrix ops)
- matplotlib or similar (for visualization in helpers.py)
- CLI via Makefile (make targets)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    Orchestrator["Makefile"]:::orchestration
    %% Data Layer
    RawData["Raw Data\ndata/data.csv"]:::data
    Preprocessor["split_dataset.py"]:::process
    SplitData["Train/Test Sets\n(data/train.csv,\n data/test.csv)"]:::data
    %% Model Layer
    ModelModule["Model.py"]:::model
    Helpers["helpers.py"]:::model
    %% Execution Scripts
    TrainEngine["train.py"]:::process
    PredictEngine["predict.py"]:::process
    %% Artifacts
    ModelFile["Serialized Model\n(model.pkl)"]:::artifacts
    LossPlot["Learning Curves\n(loss_plot.png)"]:::artifacts
    Predictions["Predictions\n(predictions.csv)"]:::artifacts

    %% Data Flow
    RawData -->|"reads"| Preprocessor
    Preprocessor -->|"writes train.csv,\n test.csv"| SplitData

    %% Training Flow
    SplitData -->|"uses train.csv"| TrainEngine
    TrainEngine -->|"imports"| ModelModule
    TrainEngine -->|"imports"| Helpers
    TrainEngine -->|"outputs"| ModelFile
    TrainEngine -->|"outputs"| LossPlot

    %% Prediction Flow
    SplitData -->|"uses test.csv"| PredictEngine
    PredictEngine -->|"loads model.pkl"| ModelFile
    PredictEngine -->|"outputs"| Predictions

    %% Orchestration Flow
    Orchestrator -.->|install, split| Preprocessor
    Orchestrator -.->|train| TrainEngine
    Orchestrator -.->|predict| PredictEngine

    %% Click Events
    click Orchestrator "https://github.com/oularefodos/multi-layer-perceptron/tree/main/Makefile"
    click RawData "https://github.com/oularefodos/multi-layer-perceptron/blob/main/data/data.csv"
    click Preprocessor "https://github.com/oularefodos/multi-layer-perceptron/blob/main/src/split_dataset.py"
    click ModelModule "https://github.com/oularefodos/multi-layer-perceptron/blob/main/src/Model.py"
    click Helpers "https://github.com/oularefodos/multi-layer-perceptron/blob/main/src/helpers.py"
    click TrainEngine "https://github.com/oularefodos/multi-layer-perceptron/blob/main/src/train.py"
    click PredictEngine "https://github.com/oularefodos/multi-layer-perceptron/blob/main/src/predict.py"

    %% Styles
    classDef data fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef process fill:#C5F7C5,stroke:#333,stroke-width:1px
    classDef model fill:#F7C5A5,stroke:#333,stroke-width:1px
    classDef artifacts fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef orchestration stroke:#000,stroke-dasharray: 5 5,fill:none
```
