# bmaltais/kohya_ss architecture

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

- Interactive diagram: https://gitdiagram.com/bmaltais/kohya_ss
- Repository: https://github.com/bmaltais/kohya_ss

## Overview

##### Project Type and Purpose
- This is a specialized GUI tool (full-stack, single-page web app) built on Gradio that wraps and orchestrates Kohya’s Stable Diffusion training scripts (sd-scripts).
- Its primary function is to let users configure model-training parameters via a web interface, generate the corresponding CLI commands, execute them (locally or in container), and display results (logs, sample images).

##### File Structure
- Top-level “entry points”:
– gui.sh, gui.bat, gui.ps1, gui-uv.sh, gui-uv.bat – scripts to launch the Gradio server (legacy “pip” and UV/uvicorn-based methods)
– kohya_gui.py – main Python script that initializes the Gradio interface
– Dockerfile & docker-compose.yaml – containerization and deployment definitions
- Core backend package:
– kohya_gui/ – contains ~50 class_*.py modules (each GUI tab, configuration loader, command executor, logging, localization)
– tools/ – utility scripts to prepare images, presets, convert formats, etc.
– config example.toml & config_files/ – default and platform-specific settings for accelerate, Runpod
– presets/, models/, dataset/ – user data volumes for training inputs, model storage, outputs
- Supporting directories: docs/, examples/, test/, assets/ (JS, CSS for styling and localization)

##### Key Insights from README
- Front-end: Gradio UI that serves on port 7860 (can be shared or headless)
- Back-end: builds CLI commands and either shells out or imports sd-scripts with accelerate
- Deployment: supports native (Windows, Linux, macOS), Docker, Runpod, Novita
- Logging & monitoring: TensorBoard runs in a separate container via docker-compose

##### Main Components & Their Interactions
A. User’s Web Browser
– Interacts with Gradio front-end over HTTP(S).
B. Gradio Server (View)
– kohya_gui.py + assets/js/*.js + assets/style.css
– Renders pages, handles input forms, displays outputs.
C. Backend Controller (Controller)
– kohya_gui/class_*.py modules:
- class_basic_training, class_advanced_training – gather parameters
- class_command_executor – builds and launches CLI commands
- class_configuration_file – loads/saves config.toml or presets
- custom_logging – collects stdout/“TensorBoard logs” for UI
– tools/ scripts invoked as needed for preprocessing.
D. Training Engine (Model)
– External sd-scripts (train_network.py, train_db, train_lllite, etc.)
– Accelerate library orchestrates multi-GPU or single GPU runs.
– Huggingface-hub, diffusers – download/upload pre-trained models.
E. Data Storage & Volumes
– dataset/ (inputs, masks), models/ (checkpoints), outputs/ (sample images), logs/
– presets/ (default and user-provided JSON configurations)
F. Monitoring & Visualization
– TensorBoard: separate container in docker-compose, mounts same logs volume.
G. Containerization & Deployment
– Dockerfile: builds the image, installs dependencies, expects /dataset volume.
– docker-compose.yaml: kicks off Gradio container + TensorBoard container + optional Postgres or storage.
– Runpod/Novita templates wrap the same Docker logic.
H. External Services
– GitHub (code updates), Huggingface Hub (model weights), optional authentication for sharing.

##### Architectural Patterns & Design Principles
- MVC-inspired separation:
– View = Gradio front-end ( kohya_gui.py + assets )
– Controller = kohya_gui/class_*.py orchestration layer
– Model = CLI training scripts + data files + presets
- Plugin-style GUI tabs: each class_*.py is a self-contained tab/controller
- CLI wrapper pattern: generate shell commands or direct Python calls
- Volume-based configuration: config.toml, presets, environment files
- Container-first deployment with clear volume mounts and microservices (TensorBoard)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    Browser["User Browser"]:::external

    subgraph "View Layer (Front-end)"
        GradioUI["Gradio Server\n(Python 3.10 + Gradio)"]:::frontend
    end

    subgraph "Controller Layer (Back-end)"
        BasicTrain["Basic Training Tab"]:::backend
        AdvancedTrain["Advanced Training Tab"]:::backend
        CommandExec["Command Executor"]:::backend
        ConfigFile["Configuration File Handler"]:::backend
        LoggingComp["Logging Component"]:::backend
        TensorboardComp["TensorBoard Controller"]:::backend
        HfComp["Huggingface Integration"]:::backend
        CommonGUI["Common GUI Utilities"]:::backend
        Localization1["Localization"]:::backend
        Localization2["Extended Localization"]:::backend
    end

    subgraph "Tooling & Preprocessing"
        Tools["tools/* scripts"]:::backend
    end

    subgraph "Training Engine (Model)"
        SDscripts["sd-scripts/*"]:::model
        Accelerate["Accelerate Configs"]:::model
    end

    subgraph "Data Storage & Volumes"
        Dataset["dataset/"]:::storage
        ModelsVol["models/"]:::storage
        PresetsVol["presets/"]:::storage
        ConfigExample["config example.toml"]:::storage
        ConfigFiles["config_files/"]:::storage
    end

    subgraph "Monitoring & Visualization"
        TensorBoard["TensorBoard Service"]:::container
    end

    subgraph "Containerization & Deployment"
        Dockerfile["Dockerfile"]:::container
        Compose["docker-compose.yaml"]:::container
        LaunchScripts["Native Launch Scripts"]:::container
    end

    subgraph "External Services"
        GitHub["GitHub (Code Updates)"]:::external
        Huggingface["Huggingface Hub"]:::external
    end

    %% Connections
    Browser -->|"HTTP(S) requests"| GradioUI
    GradioUI -->|"form data"| BasicTrain
    GradioUI -->|"form data"| AdvancedTrain
    BasicTrain -->|"collect params"| CommandExec
    AdvancedTrain -->|"collect params"| CommandExec
    CommandExec -->|"invoke tools"| Tools
    CommandExec -->|"spawn CLI command"| SDscripts
    Tools -->|"preprocess inputs"| SDscripts
    SDscripts -->|"write checkpoints/logs"| ModelsVol
    SDscripts -->|"write outputs"| Dataset
    SDscripts -->|"use configs"| Accelerate
    SDscripts -->|"download/upload models"| Huggingface
    CommandExec -->|"load/save configs"| ConfigFile
    CommandExec -->|"log stdout"| LoggingComp
    LoggingComp -->|"stream logs"| GradioUI
    ModelsVol -->|"mount volume"| TensorBoard
    Dataset -->|"mount volume"| TensorBoard
    GradioUI -->|"display logs/images"| Browser
    Dockerfile -->|"build image"| Compose
    Compose -->|"starts"| GradioUI
    Compose -->|"starts"| TensorBoard
    Compose -->|"mounts volumes"| Dataset
    Compose -->|"mounts volumes"| ModelsVol
    GitHub -->|"code updates"| Dockerfile

    %% Click Events
    click GradioUI "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui.py"
    click GradioUI "https://github.com/bmaltais/kohya_ss/blob/master/assets/js/script.js"
    click GradioUI "https://github.com/bmaltais/kohya_ss/blob/master/assets/js/localization.js"
    click GradioUI "https://github.com/bmaltais/kohya_ss/blob/master/assets/style.css"
    click BasicTrain "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_basic_training.py"
    click AdvancedTrain "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_advanced_training.py"
    click CommandExec "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_command_executor.py"
    click ConfigFile "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_configuration_file.py"
    click LoggingComp "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/custom_logging.py"
    click TensorboardComp "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_tensorboard.py"
    click HfComp "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/class_huggingface.py"
    click CommonGUI "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/common_gui.py"
    click Localization1 "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/localization.py"
    click Localization2 "https://github.com/bmaltais/kohya_ss/blob/master/kohya_gui/localization_ext.py"
    click Tools "https://github.com/bmaltais/kohya_ss/tree/master/tools/"
    click SDscripts "https://github.com/bmaltais/kohya_ss/tree/master/sd-scripts/"
    click Accelerate "https://github.com/bmaltais/kohya_ss/blob/master/config_files/accelerate/default_config.yaml"
    click Dataset "https://github.com/bmaltais/kohya_ss/tree/master/dataset/"
    click ModelsVol "https://github.com/bmaltais/kohya_ss/tree/master/models/"
    click PresetsVol "https://github.com/bmaltais/kohya_ss/tree/master/presets/"
    click ConfigExample "https://github.com/bmaltais/kohya_ss/blob/master/config example.toml"
    click ConfigFiles "https://github.com/bmaltais/kohya_ss/tree/master/config_files/"
    click Dockerfile "https://github.com/bmaltais/kohya_ss/tree/master/Dockerfile"
    click Compose "https://github.com/bmaltais/kohya_ss/blob/master/docker-compose.yaml"
    click LaunchScripts "https://github.com/bmaltais/kohya_ss/blob/master/gui.sh"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4B8BBE;
    classDef backend fill:#DFFFD6,stroke:#4B8BBE;
    classDef model fill:#FFE4B3,stroke:#DE7E00;
    classDef storage fill:#E0E0E0,stroke:#666666;
    classDef external fill:#F4D4FF,stroke:#A020F0;
    classDef container fill:#FFEBE8,stroke:#B22222;
```
