# saiyan-world/goku architecture

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

- Interactive diagram: https://gitdiagram.com/saiyan-world/goku
- Repository: https://github.com/saiyan-world/goku

## Overview

##### Project Type and Purpose
- This is a research-oriented deep learning project focused on generative models for images and videos using rectified flow transformers. The primary purpose is to generate high-quality visuals based on text or images.
- The README provides performance benchmarks and comparisons which indicate that behind the scenes, there is an intricate model design and data curation process that underpins the generative capabilities.

##### High-Level Components
a. Configuration/Setup Module:
- “configs” directory (with goku_2b.yaml and goku_8b.yaml). These YAML files likely provide the different model configurations (e.g., model sizes, hyperparameters) for various variants of the model.
- A “Configuration Loader” component which reads and processes these settings.

b. Core Model Architecture:
- “goku” directory, in particular the model defined in goku/model.py. This is the core of the system, encapsulating the implementation of the flow-based video and image generative processes.
- This block with keywords like “Rectified Flow Transformers,” “Image/Video Token Interaction,” and “Generative Pipeline” to reflect the technical essence described in the README.
- If needed, include sub-components like input preprocessing, token embedding, flow formulation, and output generation (even if these are abstracted within model.py, it is useful for clarity).

c. Auxiliary Tools:
- “tools” directory, specifically the download_flan_t5.py script. This likely facilitates downloading or integrating an external model (possibly “Flan-T5”) which might be used for text-to-video or text-to-image transformation.
- This as an “External Dependency Downloader or Preprocessor” that supports the core generation process.

d. Requirements and Dependency Management:
- The presence of requirements.txt indicates dependency management via Python packages.

e. Data Flow (Inferred):
- Although not explicitly in the file tree, the README’s discussion of data curation and benchmarks implies a data ingestion or preprocessing step.

- Link the auxiliary tool (download_flan_t5.py) to the dependency block or indicate that it supports external model assets.
- Data flow progressing from input (text or image data) → configuration setup → model processing (with its internal stages) → output (generated image or video).
- If applicable, annotate dependencies (like benchmark evaluation) but avoid unnecessary clutter—focus on core architecture elements.

##### Architectural Patterns / Design Principles
- Modular design: separate configuration, model logic, external tools, and dependency management.
- The modular layout suggested by the project files hints at a clean separation of concerns, which should be visually represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Data"
        DataPre["Data Curation & Preprocessing"]:::data
        Goku2B["Goku 2B Config"]:::config
        Goku8B["Goku 8B Config"]:::config
        ConfigLoader["Configuration Loader – Reads YAML Files"]:::config
        DataPre -->|"feeds"| ConfigLoader
        Goku2B -->|"provides"| ConfigLoader
        Goku8B -->|"provides"| ConfigLoader
    end

    subgraph "Core Model Pipeline"
        GokuModel["Goku Model – Core Generative Architecture<br>Rectified Flow Transformers<br>Image/Video Token Interaction<br>Generative Pipeline"]:::core
        GeneratedOutput["Generated Visual Output<br>(Image/Video)"]:::core
        ConfigLoader -->|"initializes"| GokuModel
        GokuModel -->|"produces"| GeneratedOutput
    end

    subgraph "Auxiliary & Dependencies"
        DownloadFlanT5["External Dependency Downloader<br>(Download Flan-T5)"]:::aux
        EnvDep["Environment/Dependency Manager<br>(Python Requirements)"]:::aux
        DownloadFlanT5 ---|"supports"| GokuModel
        EnvDep ---|"supports"| GokuModel
        EnvDep -->|"aids"| DownloadFlanT5
    end

    classDef config fill:#f5a623,stroke:#333,stroke-width:2px;
    classDef core fill:#6fc,stroke:#333,stroke-width:2px;
    classDef aux fill:#ccf,stroke:#333,stroke-width:2px;
    classDef data fill:#fcc,stroke:#333,stroke-width:2px;

click Goku2B "https://github.com/saiyan-world/goku/blob/main/configs/goku_2b.yaml"
click Goku8B "https://github.com/saiyan-world/goku/blob/main/configs/goku_8b.yaml"
click GokuModel "https://github.com/saiyan-world/goku/blob/main/goku/model.py"
click DownloadFlanT5 "https://github.com/saiyan-world/goku/blob/main/tools/download_flan_t5.py"
click EnvDep "https://github.com/saiyan-world/goku/blob/main/requirements.txt"
```
