# guanyimeng/sd_svd_backend architecture

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

- Interactive diagram: https://gitdiagram.com/guanyimeng/sd_svd_backend
- Repository: https://github.com/guanyimeng/sd_svd_backend

## Overview

##### Project Type and Purpose
- This is a Python-based backend (CLI‑driven) for running three image‑generation models: Stable Diffusion 1.5 (SD), Stable Diffusion XL (SDXL), and a custom SVD model.
- It provides script entry points that accept either text prompts (SD & SDXL) or input images (SVD), then produce images or videos.

##### File Structure
- Top level:
- scripts/ : CLI entry points (SD_run.py, SDXL_run.py, SVD_run.py)
- madhouse/ : Python package containing three subpackages (SD, SDXL, SVD), each with model‑wrapping functions (e.g., SD_text2image.py)
- config/config.ini : runtime settings (e.g., model paths, inference parameters)
- inputs/ : optional source images for SVD
- outputs/ : where generated media are saved
- models/Put_models_here : placeholder for local model weights
- requirements.txt : dependency declarations (torch, huggingface_hub, others)

##### README Insights
- Prereqs: PyTorch install, `requirements.txt`, `huggingface-cli login` for model access.
- Execution: set PYTHONPATH, then run one of the scripts with a prompt or input file path.

##### Main Components
a. Entry‑Point Layer (scripts/)
- SD_run.py
- SDXL_run.py
- SVD_run.py
b. Configuration Loader
- Reads config/config.ini
c. Model Modules (madhouse/)
- madhouse.SD.SD_text2image
- madhouse.SDXL.SXDL_text2image
- madhouse.SVD.SVD_func
d. Model Weights
- Local storage (models/) or remote on Huggingface Hub
e. Inference Engine
- PyTorch runtime (GPU/CPU)
f. I/O Storage
- inputs/ (for SVD)
- outputs/ (images, videos)
g. External Services
- Huggingface Hub (model download, authentication)

##### Relationships and Data Flow
1. User invokes a script with CLI arguments.
2. Script loads config via the Configuration Loader.
3. Script calls the appropriate Model Module function.
4. Model Module checks for local weights (models/) or fetches from Huggingface Hub (via huggingface-cli+API).
5. PyTorch environment runs inference:
– SD & SDXL: text → latent → image
– SVD: input image → transform → output
6. Generated output is written to outputs/

##### Architectural Patterns & Design Principles
- Layered design: CLI layer → config → model wrapper → inference engine → storage.
- Single responsibility: separate scripts for each model, separate modules per model type.
- Extensibility: new models can be dropped into madhouse/ and new scripts can be added.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry-Point Layer
    subgraph "Entry-Point Scripts"
        SD_run["scripts/SD_run.py"]:::cli
        SDXL_run["scripts/SDXL_run.py"]:::cli
        SVD_run["scripts/SVD_run.py"]:::cli
    end

    %% Configuration Loader
    ConfigLoader["config/config.ini"]:::config

    %% Model Modules Layer
    subgraph "Model Modules"
        SD_text2image["madhouse/SD/SD_text2image.py"]:::module
        SDXL_text2image["madhouse/SDXL/SXDL_text2image.py"]:::module
        SVD_func["madhouse/SVD/SVD_func.py"]:::module
    end

    %% Storage and Services
    LocalWeights["models/Put_models_here"]:::storage
    RemoteWeights("Huggingface Hub"):::external
    Inputs["inputs/"]:::storage
    Outputs["outputs/"]:::storage

    %% Inference Engine
    Engine["PyTorch Runtime (requirements.txt)"]:::engine

    %% Data Flows
    SD_run -->|loads config| ConfigLoader
    SDXL_run -->|loads config| ConfigLoader
    SVD_run -->|loads config| ConfigLoader

    SD_run -->|invokes| SD_text2image
    SDXL_run -->|invokes| SDXL_text2image
    SVD_run -->|invokes| SVD_func

    SD_text2image -->|checks weights| LocalWeights
    SD_text2image -->|or fetches| RemoteWeights
    SDXL_text2image -->|checks weights| LocalWeights
    SDXL_text2image -->|or fetches| RemoteWeights
    SVD_func -->|reads input| Inputs
    SVD_func -->|checks weights| LocalWeights
    SVD_func -->|or fetches| RemoteWeights

    SD_text2image -->|runs inference on| Engine
    SDXL_text2image -->|runs inference on| Engine
    SVD_func -->|runs inference on| Engine

    Engine -->|writes output| Outputs

    %% Click Events
    click SD_run "https://github.com/guanyimeng/sd_svd_backend/blob/main/scripts/SD_run.py"
    click SDXL_run "https://github.com/guanyimeng/sd_svd_backend/blob/main/scripts/SDXL_run.py"
    click SVD_run "https://github.com/guanyimeng/sd_svd_backend/blob/main/scripts/SVD_run.py"
    click ConfigLoader "https://github.com/guanyimeng/sd_svd_backend/blob/main/config/config.ini"
    click SD_text2image "https://github.com/guanyimeng/sd_svd_backend/blob/main/madhouse/SD/SD_text2image.py"
    click SDXL_text2image "https://github.com/guanyimeng/sd_svd_backend/blob/main/madhouse/SDXL/SXDL_text2image.py"
    click SVD_func "https://github.com/guanyimeng/sd_svd_backend/blob/main/madhouse/SVD/SVD_func.py"
    click LocalWeights "https://github.com/guanyimeng/sd_svd_backend/tree/main/models/Put_models_here"
    click Inputs "https://github.com/guanyimeng/sd_svd_backend/tree/main/inputs/"
    click Outputs "https://github.com/guanyimeng/sd_svd_backend/tree/main/outputs/"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef config fill:#FFD700,stroke:#000,stroke-width:1px
    classDef module fill:#90EE90,stroke:#000,stroke-width:1px
    classDef storage fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef engine fill:#FFA500,stroke:#000,stroke-width:1px
```
