# ismlrn/cnn-scratch architecture

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

- Interactive diagram: https://gitdiagram.com/ismlrn/cnn-scratch
- Repository: https://github.com/ismlrn/cnn-scratch

## Overview

##### Project type and purpose
- This is a machine-learning demonstration project implementing a simple Convolutional Neural Network (CNN) from scratch, using only NumPy.
- Its goal is educational: to show how each layer (conv2d, relu, maxpool2d, flatten, dense, softmax) can be handcrafted without TensorFlow or PyTorch.

##### File structure
- All files live at the top level:
- `.py` modules (`cnn-forward.py`, `cnn-full.py`, etc.) encapsulate the core layer implementations and orchestration.
- Notebooks (`.ipynb`) provide interactive demos of forward and backward passes.
- There are no subdirectories or external services—everything is a local, linear pipeline of functions.
- The only external dependency is NumPy.

##### README for additional insights
- It confirms the six basic building blocks (conv2d, relu, maxpool2d, flatten, dense, softmax).
- It mentions `cnn-full.py` as the “main” script that chains them together with forward and backward passes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Orchestrator"
        Orchestrator["Orchestrator (cnn-full.py)"]:::orchestrator
    end
    DataInput[(Data Input)]:::data
    Orchestrator -->|seeds data| DataInput

    Conv2D["conv2d"]:::conv
    ReLU["relu"]:::activation
    MaxPool["maxpool2d"]:::pool
    Flatten["flatten"]:::flatten
    Dense["dense"]:::dense
    Softmax["softmax"]:::softmax
    Loss["Loss & Backward"]:::back

    DataInput -->|"Batch×C×H×W"| Conv2D
    Conv2D -->|"feature maps"| ReLU
    ReLU -->|"activated maps"| MaxPool
    MaxPool -->|"pooled maps"| Flatten
    Flatten -->|"flat vector"| Dense
    Dense -->|"logits"| Softmax
    Softmax -->|"probabilities"| Loss

    Loss -->|backprop grads| Softmax
    Softmax -->|∂L/∂Dense| Dense
    Dense -->|∂L/∂Flatten| Flatten
    Flatten -->|∂L/∂MaxPool| MaxPool
    MaxPool -->|∂L/∂ReLU| ReLU
    ReLU -->|∂L/∂Conv2D| Conv2D

    Conv2D -->|uses| NumPy["NumPy"]:::external
    ReLU -->|uses| NumPy
    MaxPool -->|uses| NumPy
    Flatten -->|uses| NumPy
    Dense -->|uses| NumPy
    Softmax -->|uses| NumPy
    Loss -->|uses| NumPy

    classDef conv fill:#CEE5F2,stroke:#0366D6,color:#0366D6
    classDef activation fill:#E2F0D9,stroke:#2E8B57,color:#2E8B57
    classDef pool fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef flatten fill:#F0F0F0,stroke:#A9A9A9,color:#696969
    classDef dense fill:#E6E6FA,stroke:#800080,color:#800080
    classDef softmax fill:#FECFD2,stroke:#FF0000,color:#FF0000
    classDef back stroke-dasharray: 5 5
    classDef orchestrator fill:#FFF5BA,stroke:#FFD700,color:#DAA520
    classDef data fill:#D3D3D3,stroke:#A9A9A9,color:#000000
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2

    click Orchestrator "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-full.py"
    click DataInput "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-full.py"
    click Conv2D "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click ReLU "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click MaxPool "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click Flatten "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click Dense "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click Softmax "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward.py"
    click Loss "https://github.com/ismlrn/cnn-scratch/blob/main/cnn-forward-backward.py"
```
