# rupeshs/fastsdcpu architecture

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

- Interactive diagram: https://gitdiagram.com/rupeshs/fastsdcpu
- Repository: https://github.com/rupeshs/fastsdcpu

## Overview

##### Project type and purpose
- FastSD CPU is a multi-interface image-generation engine built on Stable Diffusion, optimized for CPU (via OpenVINO), LoRA, ControlNet, and GGUF (stablediffusion.cpp) workflows.
- It provides three user interfaces (Desktop Qt GUI, Web UI, CLI) plus a REST/MCP API, and supports specialized pipelines (LCM, LCM-LoRA, OpenVINO, GGUF).

##### File structure
- Top-level “src” directory splits into “frontend” and “backend” packages.
- “src/app.py” is the entry point; it launches UIs or API/MCP servers.
- “src/backend” contains annotators (ControlNet), model-loading, pipeline implementations, device abstraction, and image-saving utilities.
- “src/frontend” holds CLI, Qt GUI, and WebUI modules.
- “configs” and “models” directories store model lists and downloaded model files (OpenVINO, LCM, LoRA, GGUF).
- Scripts like “start-webui.sh”, “start-mcpserver.sh” orchestrate different run modes.

##### README insights
- Multiple interfaces: Desktop GUI (Qt), WebUI (FastAPI + uvicorn), CLI, MCP server (Model Context Protocol).
- Pipelines: LCM, LCM-LoRA, OpenVINO int8, ControlNet annotators, GGUF via stablediffusion.cpp.
- Device support: CPU, GPU, NPU (via OpenVINO), MPS (mac), or external shared library for GGUF.

##### Main components & interactions
a. Frontend tier
- Desktop GUI (Qt widgets)
- Web UI (HTTP server + HTML/JS UI)
- CLI (interactive command line)
- External clients via MCP or REST API (Claude desktop, OpenWebUI)
b. API/Gateway layer
- app.py uses FastAPI or MCP server modules to expose endpoints (/api/generate, /mcp)
- CLI and GUI invoke the same core services through function calls
c. Core backend
- Controller: route input → correct pipeline
- Pipelines: LCM, LCM-LoRA, OpenVINO pipelines, GGUF pipeline
- Annotators: ControlNet pre- and post-processing modules
- Model loader: reads configs, loads models from “models/…” or “lora_models”/“controlnet_models”
- Device abstraction: selects CPU/GPU/NPU/MPS or stablediffusion.cpp shared library
- Image saver / encoder: stores disk files & encodes base64 to return via API
d. File system & config
- configs/*.txt: model lists
- models/…: downloaded model binaries (OpenVINO IR, safetensors, .gguf)
e. External services / dependencies
- OpenVINO toolkit
- stablediffusion.cpp shared library for GGUF
- Python dependencies (FastAPI, PyQt, uv)

##### Architectural patterns & principles
- Layered architecture: UI → API → core services → pipelines → device & model loader
- Plugin-style pipelines and annotators: each pipeline and annotator module implements a common interface for interchangeability
- Separation of concerns: distinct modules for UI, API, model handling, and device abstraction
- Configuration-driven: behavior determined by “configs” files and environment variables (DEVICE)

##### Details
- That both CLI and Desktop GUI call into the same core app.py rather than separate code paths.
- Multi-pipeline support and annotator extensions as plugin modules under the “Backend Engine”.
- Device-selection logic (CPU vs. OpenVINO vs. GGUF shared lib).
- Configs directory feeding into the Model Loader.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        CLI["CLI"]:::ui
        click CLI "https://github.com/rupeshs/fastsdcpu/blob/main/src/frontend/cli_interactive.py"
        GUI["Desktop GUI (Qt)"]:::ui
        click GUI "https://github.com/rupeshs/fastsdcpu/blob/main/src/frontend/gui/app_window.py"
        WebUI["Web UI (HTML/JS)"]:::ui
        click WebUI "https://github.com/rupeshs/fastsdcpu/blob/main/src/frontend/webui/ui.py"
        ExtClients["External Clients (MCP/REST)"]:::ui
    end

    %% API/Gateway Layer
    subgraph "API/Gateway Layer"
        direction TB
        REST["REST API (FastAPI)"]:::api
        click REST "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/api/web.py"
        MCP["MCP Server"]:::api
        click MCP "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/api/mcp_server.py"
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        Controller["Core Controller<br/>(app.py + context)"]:::core
        click Controller "https://github.com/rupeshs/fastsdcpu/blob/main/src/app.py"
    end

    %% Backend Engine
    subgraph "Backend Engine"
        direction TB
        subgraph "Pipelines"
            direction TB
            LCM["LCM Pipeline"]:::core
            click LCM "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/pipelines/lcm.py"
            LCMlora["LCM-LoRA Pipeline"]:::core
            click LCMlora "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/pipelines/lcm_lora.py"
            OpenVINO["OpenVINO Pipeline"]:::core
            click OpenVINO "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/openvino/pipelines.py"
            GGUF["GGUF Pipeline"]:::core
            click GGUF "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/gguf/gguf_diffusion.py"
        end
        Annotators["ControlNet Annotators"]:::core
        click Annotators "https://github.com/rupeshs/fastsdcpu/tree/main/src/backend/annotators/"
        Loader["Model Loader"]:::core
        click Loader "https://github.com/rupeshs/fastsdcpu/tree/main/src/backend/models/"
        Device["Device Abstraction"]:::device
        click Device "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/device.py"
        Saver["Image Saver & Encoder"]:::core
        click Saver "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/image_saver.py"
        click Saver "https://github.com/rupeshs/fastsdcpu/blob/main/src/backend/base64_image.py"
    end

    %% Storage & Config
    subgraph "Storage & Config"
        direction TB
        Configs["Configuration Files"]:::storage
        click Configs "https://github.com/rupeshs/fastsdcpu/tree/main/configs"
        GGUFStore["GGUF Models"]:::storage
        click GGUFStore "https://github.com/rupeshs/fastsdcpu/tree/main/models/gguf/"
        LoRAStore["LoRA Models"]:::storage
        click LoRAStore "https://github.com/rupeshs/fastsdcpu/blob/main/lora_models/Readme.txt"
        CNetStore["ControlNet Models"]:::storage
        click CNetStore "https://github.com/rupeshs/fastsdcpu/blob/main/controlnet_models/Readme.txt"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OVINO["OpenVINO Toolkit"]:::external
        SDCpp["stablediffusion.cpp Lib"]:::external
    end

    %% Connections
    CLI --> Controller
    GUI --> Controller
    WebUI --> REST
    ExtClients --> REST
    ExtClients --> MCP
    REST --> Controller
    MCP --> Controller

    Controller --> LCM
    Controller --> LCMlora
    Controller --> OpenVINO
    Controller --> GGUF

    Annotators --> LCM
    Annotators --> LCMlora

    Loader --> LCM
    Loader --> LCMlora
    Loader --> OpenVINO
    Loader --> GGUF

    Device --> LCM
    Device --> OpenVINO
    Device --> GGUF

    LCM --> Saver
    LCMlora --> Saver
    OpenVINO --> Saver
    GGUF --> Saver

    Configs --> Loader
    GGUFStore --> Loader
    LoRAStore --> Loader
    CNetStore --> Loader

    OVINO --> OpenVINO
    SDCpp --> GGUF

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#4A90E2,color:#000;
    classDef api fill:#DFFFE0,stroke:#5CB85C,color:#000;
    classDef core fill:#FFE6CC,stroke:#F0AD4E,color:#000;
    classDef device fill:#E8D0FF,stroke:#8A2BE2,color:#000;
    classDef storage fill:#F0F0F0,stroke:#A0A0A0,color:#000;
    classDef external fill:#FFE0E0,stroke:#D9534F,color:#000;
```
