# genai-2025-project/yagang-yetanothergamengen- architecture

> Architecture diagram of the GitHub repository genai-2025-project/yagang-yetanothergamengen-, 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/genai-2025-project/yagang-yetanothergamengen-
- Repository: https://github.com/genai-2025-project/yagang-yetanothergamengen-

## Overview

##### Project Type & Purpose
- This is an ML research pipeline for a single diffusion model that learns next-frame prediction across four games (Chess, Snake, Car Avoid, Game of Life).
- It comprises dataset generation, model finetuning/training, and inference.

##### File Structure
- Top level:
- Inference.ipynb – Jupyter notebook to run the trained model
- train.py – script to train the diffusion (UNet) model
- finetune_decoder.py – script to finetune the VAE decoder
- *_dataset.py – four scripts to generate raw datasets
- utils/ – helper modules for counting transitions, CSV conversion, visualization
- requirements.txt, LICENSE, README.md
- No web frontend or REST APIs; everything runs as Python scripts/notebooks.

##### Pull Key Details from README
- Model checkpoints and dataset hosted on Hugging Face.
- Uses Stable Diffusion 1.5V backbone: repurposes VAE encoder + UNet.
- Training uses `accelerate launch train.py` on multi-GPU.
- Inference runs in Jupyter, consumes GPU/ARM hardware.

##### Main Components & Their Relationships
a. Dataset Generation
- Four scripts (`chess_dataset.py`, `snake_dataset.py`, etc.)
- Output: raw image sequences + transition metadata stored in `~/dataset/`.
- Utils support CSV conversion, transition counts, and visualization.
b. Model Preparation
- VAE Decoder Finetuning (`finetune_decoder.py`):
- Inputs: pre-trained Stable Diffusion VAE decoder + game images
- Outputs: finetuned VAE decoder weights
c. Model Training
- Training script (`train.py`):
- Inputs: finetuned VAE decoder, dataset, conditioning (previous frame + action)
- Framework: Hugging Face Diffusers + `accelerate` (multi-GPU)
- Outputs: UNet model checkpoints under `./training_diffusion/`
d. Model Hosting & Storage
- Checkpoints & datasets pushed to Hugging Face Hub
- Local disk for intermediate artifacts (`~/dataset/`, `./training_diffusion/`)
e. Inference Engine
- Jupyter Notebook (`Inference.ipynb`):
- Loads model checkpoints from local or HF
- Provides CLI-style interface to select game, sends actions, receives frames
- Requires ~8 GB VRAM or runs on ARM MacBooks
f. External Services
- Hugging Face Hub for hosting datasets & model checkpoints
- Python package index for dependencies (torch, diffusers, accelerate, etc.)

##### Architectural Patterns & Design Principles
- Pipeline pattern: clear separation of data generation → pretraining/finetuning → training → inference.
- Modularity: each game dataset script is interchangeable (single upstream pipeline).
- Reuse of foundation models (Stable Diffusion VAE + UNet) for multi-domain learning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Generation Stage
    subgraph "Data Generation"
        ds1["Chess Dataset Generator"]:::data
        ds2["Snake Dataset Generator"]:::data
        ds3["Car Avoid Dataset Generator"]:::data
        ds4["Game of Life Dataset Generator"]:::data
    end

    %% Storage
    storage["Dataset Storage\n~/dataset/"]:::storage

    %% Utilities
    subgraph "Utilities"
        u1["Transition Counting Utility"]:::data
        u2["CSV Conversion Utility"]:::data
        u3["Dataset Visualization Utility"]:::data
    end

    %% Model Preparation
    subgraph "Model Preparation"
        finetune["VAE Decoder Finetuner"]:::model
    end

    %% Training Stage
    subgraph "Training"
        core["Diffusion Engine\n(VAE + UNet)"]:::model
        train["Diffusion Model Trainer"]:::orchestration
        storage2["Training Checkpoints\n./training_diffusion/"]:::storage
    end

    %% Hosting
    subgraph "Hosting"
        hf["Hugging Face Hub"]:::external
        local["Local Storage\nIntermediate Artifacts"]:::storage
    end

    %% Inference
    subgraph "Inference"
        nb["Inference Engine Notebook"]:::orchestration
        user["User (Game Commands)"]:::external
    end

    %% Project Meta
    subgraph "Project Meta"
        readme["Project Documentation"]:::external
        req["Dependencies Specification"]:::external
    end

    %% Data Flows
    ds1 -->|"64×64 frames + metadata"| storage
    ds2 -->|"64×64 frames + metadata"| storage
    ds3 -->|"64×64 frames + metadata"| storage
    ds4 -->|"64×64 frames + metadata"| storage

    storage -->|"counts, csv, viz"| u1
    storage -->|"counts, csv, viz"| u2
    storage -->|"counts, csv, viz"| u3

    storage -->|"raw images"| finetune
    finetune -->|"finetuned VAE weights"| train
    storage -->|"latent dataset + actions"| train

    train -->|"model checkpoints"| storage2
    storage2 -->|"push/pull"| hf
    storage2 -->|"local backup"| local

    hf -->|"load checkpoints"| nb
    local -->|"load checkpoints"| nb
    user -->|"send actions"| nb
    nb -->|"return frames"| user

    %% Click Events
    click ds1 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/chess_dataset.py"
    click ds2 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/snake_dataset.py"
    click ds3 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/car_dataset.py"
    click ds4 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/game_of_life_dataset.py"
    click u1 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/utils/count_transitions_utils.py"
    click u2 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/utils/to_csv_utils.py"
    click u3 "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/utils/visualize_dataset_utils.ipynb"
    click finetune "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/finetune_decoder.py"
    click train "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/train.py"
    click nb "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/Inference.ipynb"
    click readme "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/README.md"
    click req "https://github.com/genai-2025-project/yagang-yetanothergamengen-/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef model fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef orchestration fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef storage fill:#B3E5FC,stroke:#0277BD,color:#01579B
```
