# mpezeshki/pytorch_forward_forward architecture

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

- Interactive diagram: https://gitdiagram.com/mpezeshki/pytorch_forward_forward
- Repository: https://github.com/mpezeshki/pytorch_forward_forward

## Overview

Step 1: Identify Project Type and Purpose
- This is a single-script PyTorch implementation of Geoffrey Hinton’s Forward-Forward (FF) training algorithm, intended for MNIST digit classification as an alternative to back-propagation.
- The project contains one entry point (main.py), an image folder for documentation (imgs/), and standard metadata files (.gitignore, LICENSE, README.md).

Step 2: Analyze the File Structure
- main.py: orchestrates data loading, model definition, local forward-forward training loops, and evaluation.
- README.md: explains algorithm, sample generation, local objectives, and usage.

Step 3: Examine README for Insights
- Core components described:
- Positive and negative sample merge (image+label vs. image+random_label)
- Local threshold-based objective at each layer
- Sequential training of layers without backward pass
- Final prediction by maximizing total layer activations
- Dependencies: Python, PyTorch, torchvision (for MNIST).

a. Main Components:
1. Data Loader
2. Positive Sample Generator
3. Negative Sample Generator
4. Layer Modules (Layer 1, Layer 2, …, Layer N)
5. Local Training Objectives (per layer)
6. Training Orchestrator (main loop)
7. Prediction Engine
8. External Frameworks (PyTorch, torchvision)

b. Relationships & Interactions:
- Data Loader → Positive/Negative Sample Generators
- Each Generator → Feed inputs to each Layer Module
- Layer Module ↔ Local Training Objective (computes local loss)
- Training Orchestrator sequences Layer-wise training
- After training, Prediction Engine queries all y ∈ [0..9]; sends (x,y) through Layers → selects y with max total activation.

c. Architectural Patterns:
- Pipeline of self-contained “learning blocks” (layers) each with own local objective.
- Single-process, sequential orchestration (no distributed or microservice architecture).

d. Key Technologies:
- Python interpreter
- PyTorch nn.Module for layer definitions
- torchvision.datasets.MNIST
- CLI entry point in main.py

- That “frontend” is the CLI/user invoking main.py, “backend” is the PyTorch pipeline.
- No separate UI or web layer; it’s a batch training application.
- How images in imgs/ document architecture but are not part of runtime.

1. Rectangles for each component (Data Loader, Sample Generators, Layer Modules, Training Orchestrator, Prediction Engine).
- From Data Loader → Sample Generators
- From Generators → Layer Modules
- From Layer Modules → Local Objectives
- From Layer Modules → Next Layer (during forward pass)
- From Prediction Engine → Output decision

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Orchestrator
    User["User / CLI"]:::cli --> Orchestrator["main.py\n(Training Orchestrator)"]:::orchestration
    click Orchestrator "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"

    %% Data Components
    Orchestrator --> DataLoader["MNIST Data Loader"]:::data
    click DataLoader "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
    DataLoader -->|"raw images"| PosGen["Positive Sample Generator"]:::data
    click PosGen "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
    DataLoader -->|"raw images"| NegGen["Negative Sample Generator"]:::data
    click NegGen "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"

    %% Model Layers Pipeline
    subgraph "Model Layers"
        direction TB
        PosGen -->|"pos sample"| Layer1["Layer 1\n(Local Objective)"]:::model
        click Layer1 "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
        NegGen -->|"neg sample"| Layer1
        Layer1 -->|"activations"| Layer2["Layer 2\n(Local Objective)"]:::model
        click Layer2 "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
        Layer2 -->|"activations"| Layer3["Layer 3\n(Local Objective)"]:::model
        click Layer3 "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
        Layer3 -->|"activations"| LayerN["Layer N\n(Local Objective)"]:::model
        click LayerN "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
    end

    %% Prediction Engine
    LayerN --> Prediction["Prediction Engine"]:::orchestration
    click Prediction "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/main.py"
    Prediction -->|"predicted y"| Output["Output y"]
    
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::external
        click PyTorch "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/README.md"
        torchvision["torchvision"]:::external
        click torchvision "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/README.md"
    end

    %% Resources & Documentation
    subgraph "Resources & Metadata"
        direction TB
        README["README.md"]:::docs
        click README "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/README.md"
        Imgs["imgs/"]:::docs
        click Imgs "https://github.com/mpezeshki/pytorch_forward_forward/tree/main/imgs/"
        LICENSEf["LICENSE"]:::docs
        click LICENSEf "https://github.com/mpezeshki/pytorch_forward_forward/tree/main/LICENSE"
        Gitignore[".gitignore"]:::docs
        click Gitignore "https://github.com/mpezeshki/pytorch_forward_forward/blob/main/.gitignore"
    end

    %% Styles
    classDef data fill:#D6EAF8,stroke:#217DBB,color:#154360;
    classDef model fill:#D5F5E3,stroke:#239B56,color:#1D8348;
    classDef orchestration fill:#FCF3CF,stroke:#F4D03F,color:#7D6608;
    classDef external fill:#F2F3F4,stroke:#B2BABB,color:#616A6B;
    classDef docs fill:#EBDEF0,stroke:#AF7AC5,color:#6C3483;
    classDef cli fill:#FADBD8,stroke:#EC7063,color:#78281F;
```
