# bytedance/dreamo architecture

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

- Interactive diagram: https://gitdiagram.com/bytedance/dreamo
- Repository: https://github.com/bytedance/dreamo

## Overview

##### Project Type and Purpose
- DreamO is a Python-based image-generation framework with:
- A CLI/Gradio demo entrypoint (app.py)
- A modular ML pipeline for image customization (dreamo/dreamo_pipeline.py)
- Transformers and utilities supporting tasks (dreamo/transformer.py, dreamo/utils.py)
- Optional benchmarking tools (tools/BEN2.py)
- Model assets in models/
- Purpose: Load user inputs (e.g., reference images, style flags), run an inference pipeline with optional quantization or CPU offload, and output customized images via Gradio or CLI.

##### High-Level Components

A. Presentation Layer
- Component: Gradio Web UI & CLI Entrypoint (app.py)
- Role: Parse command-line flags (--int8, --offload, --no_turbo), collect user inputs, display outputs.
- Technology: Python, Gradio, argparse

B. Orchestration Layer
- Component: dreamo_pipeline.py
- Role: Coordinate preprocessing, transformer calls, model loading, postprocessing.
- Pattern: Facade over lower-level modules for each supported task (IP, ID, Try-On, Style, Multi).

C. Core Processing Layer
- Component 1: Transformer Module (transformer.py)
– Sets up PyTorch model (Diffusers + VAE + FLUX-LoRA)
– Applies int8 quantization (optimum-quant) or CPU offload if requested
- Component 2: Utility Module (utils.py)
– Image I/O, tensor conversions, feature encoding (VAE), logging
- Data: Model weights stored in models/ (LoRA adapters, base checkpoints)

D. External Services & Infrastructure
- Hugging Face Hub (for downloading base and adapter models)
- Local GPU/CPU resources
- Optional: benchmarking script (tools/BEN2.py)

##### Relationships and Data Flow
- Auxiliary: dreamo_pipeline ↔ utils (for preprocessing), tools/BEN2.py → dreamo_pipeline (benchmarks throughput)

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI/CLI separated from core logic.
- Modular Pipeline: Each task plugged into a unified framework.
- Configurable Hardware Acceleration: Flags trigger int8 quantization or CPU offload.
- Extensibility: New tasks or adapters can be added under dreamo/ modules.

##### Technologies & Frameworks to Annotate
- Python 3.10
- PyTorch 2.6.0, optimum-quant
- Hugging Face Diffusers & Transformers
- VAE feature encoder
- FLUX-LoRA adapters
- Gradio for UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::ui
        App["Gradio UI & CLI Entrypoint\n(app.py)"]:::module
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Pipeline["DreamO Pipeline Facade\n(dreamo_pipeline.py)"]:::module
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        direction TB
        Transformer["Transformer Module\n(transformer.py)"]:::module
        Utils["Utility Module\n(utils.py)"]:::module
        Models["Model Weights\n(models/)"]:::storage
    end

    %% External Services & Infrastructure
    subgraph "External Services & Infrastructure"
        direction TB
        HF["Hugging Face Hub"]:::external
        Resources["Local GPU/CPU Resources"]:::external
        BENCH["Benchmarking Tool\n(BEN2.py)"]:::module
    end

    %% Data Flow
    User -->|"inputs: images, flags"| App
    App -->|"start(task)"| Pipeline
    Pipeline -->|"load_model()"| Transformer
    Pipeline -->|"run_inference()"| Transformer
    Pipeline -->|"preprocess() / postprocess()"| Utils
    Transformer -->|"loads weights"| Models
    Transformer -->|"quantize/offload"| Resources
    HF -->|"download models"| Transformer
    BENCH -->|"benchmark call"| Pipeline
    Pipeline -->|"results tensor"| Utils
    Utils -->|"processed output"| App
    App -->|"display/save"| User

    %% Optional Flags Branch
    App -->|"--int8"| Transformer
    App -->|"--offload"| Transformer

    %% Click Events
    click App "https://github.com/bytedance/dreamo/blob/main/app.py"
    click Pipeline "https://github.com/bytedance/dreamo/blob/main/dreamo/dreamo_pipeline.py"
    click Transformer "https://github.com/bytedance/dreamo/blob/main/dreamo/transformer.py"
    click Utils "https://github.com/bytedance/dreamo/blob/main/dreamo/utils.py"
    click Models "https://github.com/bytedance/dreamo/tree/main/models/"
    click BENCH "https://github.com/bytedance/dreamo/blob/main/tools/BEN2.py"

    %% Styles
    classDef module fill:#cce5ff,stroke:#1f77b4,stroke-width:1px
    classDef storage fill:#ffe5cc,stroke:#ff7f0e,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#999999,stroke-width:1px
    classDef ui fill:#d4edda,stroke:#28a745,stroke-width:1px
```
