# ghif/diffusion-keras3 architecture

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

- Interactive diagram: https://gitdiagram.com/ghif/diffusion-keras3
- Repository: https://github.com/ghif/diffusion-keras3

## Overview

##### Project Type and Purpose
- This is a machine-learning research & experimentation project that implements Denoising Diffusion Implicit Models (DDIM) in Keras/TensorFlow.
- Purpose: Train and evaluate a configurable U-Net diffusion model on CIFAR-10, then run inference (image generation) and optional simple UIs (text2img, img2img).

##### File Structure
- Root scripts:
- training.py – full training pipeline (data load, preprocess, model build, train, EMA, checkpoint/save).
- inference.py – runs reverse diffusion to generate images from noise.
- text2image_sd3.py, image2image_sd3.py – specialized inference variants.
- ui_text2img.py, ui_img2img.py – lightweight UI wrappers (likely streamlit or TKinter).
- Libraries & modules:
- architectures.py – U-Net backbone definitions.
- ddim.py – core diffusion process logic (forward & reverse steps).
- constants.py – global hyperparameters & config.
- utils.py – data visualization, helper I/O.
- assets: images/ – example gifs; models/ (implied) – stored checkpoints.

##### README Insights
- Uses TensorFlow/Keras, NumPy, Matplotlib.
- Training flow: load CIFAR-10 → diffusion forward model → back-diffusion reverse → EMA averaging → checkpoint & sample outputs.
- Inference: reverse diffusion loop CLI.
- Configurable via constants.py.

##### Main Components
a. Data Layer
- CIFAR-10 Downloader/Loader
- Preprocessor (normalization, augmentation)
b. Model Definition
- Architectures module (U-Net backbone)
- DDIM core class (timesteps, scheduling)
c. Training Pipeline
- Diffusion forward pass (noise schedules)
- Reverse pass (loss, backprop via Keras)
- EMA Model Averager
- Checkpoint Saver (models/)
d. Inference Pipeline
- Loader for trained checkpoints
- Reverse diffusion sampler
- Specialized inference scripts (text2img, img2img)
e. UI Layer (optional)
- ui_text2img.py
- ui_img2img.py
f. Utilities
- Visualization (Matplotlib GIFs)
- Helpers (logging, config loading)

##### Relationships and Data Flows
- Data Layer → Training Pipeline → Checkpoint Storage
- Training Pipeline ←→ Model Definition & Constants
- Checkpoint Storage → Inference Pipeline → Output Images
- Inference Pipeline → Utilities (save/display results)
- UI Layer interacts with Inference Pipeline and Utilities
- All components share global config from constants.py

##### Architectural Patterns & Design Principles
- Modular separation: model (architectures.py & ddim.py), pipeline (training.py), utilities.
- Single-responsibility scripts (one for training, one for inference, wrappers for UIs).
- Config-driven behavior (constants.py centralizes hyperparameters).
- CLI-driven execution for reproducibility.

##### Technologies & Frameworks
- TensorFlow / Keras (model definition & training loops)
- NumPy (data array ops)
- Matplotlib (visualization/gif creation)
- CIFAR-10 dataset (TensorFlow Datasets or Keras API)
- Python GUI or CLI for UIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration
    config["Global Config & Hyperparameters\n(constants.py)"]:::config

    %% Data Layer
    data["CIFAR-10 Data Loader & Preprocessor\n(training.py)"]:::data

    %% Model Definition
    subgraph "Model Definition"
        direction TB
        arch["U-Net Architecture\n(architectures.py)"]:::compute
        ddim["DDIM Core\n(ddim.py)"]:::compute
    end

    %% Training Pipeline
    training["Training Pipeline\n(training.py)"]:::compute

    %% Checkpoint Storage
    storage["Checkpoint & Sample Outputs\n(images/)"]:::storage

    %% Inference Pipeline
    inference["Inference Pipeline\n(inference.py)"]:::compute

    %% Specialized Inference Variants
    text_var["Text-to-Image Variant\n(text2image_sd3.py)"]:::compute
    img_var["Image-to-Image Variant\n(image2image_sd3.py)"]:::compute

    %% UI Layer
    ui_text["UI Text2Image\n(ui_text2img.py)"]:::ui
    ui_img["UI Image2Image\n(ui_img2img.py)"]:::ui

    %% Utilities
    utils["Utilities\n(utils.py)"]:::utils

    %% Flows
    config -->|configures| training
    config -->|configures| inference
    config -->|configures| ui_text
    config -->|configures| ui_img

    data -->|normalized data| training
    arch -->|model blueprint| training
    ddim -->|diffusion logic| training

    training -->|trained weights| storage
    storage -->|loaded checkpoints| inference

    inference -->|generated samples| utils

    inference -->|CLI interface| text_var
    inference -->|CLI interface| img_var

    text_var -->|results| utils
    img_var -->|results| utils

    ui_text -->|invokes| text_var
    ui_img -->|invokes| img_var
    ui_text -->|uses| utils
    ui_img -->|uses| utils

    %% Click Events
    click data "https://github.com/ghif/diffusion-keras3/blob/main/training.py"
    click arch "https://github.com/ghif/diffusion-keras3/blob/main/architectures.py"
    click ddim "https://github.com/ghif/diffusion-keras3/blob/main/ddim.py"
    click config "https://github.com/ghif/diffusion-keras3/blob/main/constants.py"
    click training "https://github.com/ghif/diffusion-keras3/blob/main/training.py"
    click storage "https://github.com/ghif/diffusion-keras3/tree/main/images/"
    click inference "https://github.com/ghif/diffusion-keras3/blob/main/inference.py"
    click text_var "https://github.com/ghif/diffusion-keras3/blob/main/text2image_sd3.py"
    click img_var "https://github.com/ghif/diffusion-keras3/blob/main/image2image_sd3.py"
    click ui_text "https://github.com/ghif/diffusion-keras3/blob/main/ui_text2img.py"
    click ui_img "https://github.com/ghif/diffusion-keras3/blob/main/ui_img2img.py"
    click utils "https://github.com/ghif/diffusion-keras3/blob/main/utils.py"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1976D2,color:#0D47A1
    classDef compute fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef storage fill:#B3E5FC,stroke:#0288D1,color:#01579B
    classDef ui fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef utils fill:#ECEFF1,stroke:#546E7A,color:#263238
    classDef config fill:#E0E0E0,stroke:#9E9E9E,color:#424242
```
