# bghira/simpletuner architecture

> Architecture diagram of the GitHub repository bghira/simpletuner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bghira/simpletuner
- Repository: https://github.com/bghira/simpletuner

## Overview

SimpleTuner is a multimodal diffusion-model training toolkit with a Web UI, CLI, and multi-user worker platform. The principal workflow configures a training job, obtains and prepares data, trains a supported model, and monitors results; the Web UI also supports checkpoint inference and cloud-worker orchestration. The README documents broad capabilities, while sampled source shows selected server, process, inference, and model-pipeline behavior. Links for unsampled subsystems rely on README statements, not source inspection.

Main entry points: [`simpletuner/simpletuner_sdk/server/app.py`](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/app.py) (Server application), [`simpletuner/__main__.py`](https://github.com/bghira/simpletuner/blob/main/simpletuner/__main__.py) (Training runtime), [`simpletuner/cli/train.py`](https://github.com/bghira/simpletuner/blob/main/simpletuner/cli/train.py) (CLI), [`simpletuner/helpers/configuration/cmd_args.py`](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/configuration/cmd_args.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training runtime"]
  node_cli["CLI<br/>[train.py]"]
  node_config["Configuration<br/>[cmd_args.py]"]
  node_data["Dataset backends<br/>[factory.py]"]
  node_cache["Embedding cache<br/>[text_embeds.py]"]
  node_train["Training runtime<br/>[__main__.py]"]
  node_dist["Distributed training<br/>[backends.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_models["Model support"]
  node_registry["Model registry<br/>[all.py]"]
  node_model["Model pipelines<br/>[pipeline.py]"]
  node_adapters["LoRA and LyCORIS<br/>[lycoris.py]"]
end

subgraph group_web["Web interface"]
  node_webui["Web UI<br/>[sse-manager.js]"]
  node_server["Server application<br/>[app.py]"]
  node_configstore[("Config store<br/>[config_store.py]")]
  node_inference["Checkpoint inference"]
  node_process["Process manager<br/>[process_keeper.py]"]
end

subgraph group_platform["Cloud platform"]
  node_workers["Worker orchestration<br/>[worker_manager.py]"]
  node_worker["Worker agent<br/>[worker_agent.py]"]
  node_approval["Approval rules<br/>[rules_engine.py]"]
  node_storage["Cloud storage API<br/>[storage.py]"]
  node_storagebase[("Storage backend<br/>[base.py]")]
end

node_user(("User"))

node_user -->|"configures job"| node_cli
node_cli -.->|"loads settings"| node_config
node_config -.->|"selects datasets"| node_data
node_data -.->|"provides data"| node_cache
node_cache -.->|"supplies embeddings"| node_train
node_train -.->|"selects architecture"| node_registry
node_train -->|"uses sharding"| node_dist
node_train -->|"trains adapters"| node_adapters
node_train -.->|"emits logs"| node_logging
node_registry -.->|"selects pipeline"| node_model
node_user -->|"manages training"| node_webui
node_webui -.->|"sends requests"| node_server
node_server -->|"loads configs"| node_configstore
node_server -.->|"starts jobs"| node_process
node_server -.->|"routes inference"| node_inference
node_inference -->|"sends commands"| node_process
node_server -->|"manages workers"| node_workers
node_workers -->|"dispatches jobs"| node_worker
node_server -.->|"evaluates approvals"| node_approval
node_worker -->|"uploads artifacts"| node_storage
node_storage -.->|"stores objects"| node_storagebase

click node_cli "https://github.com/bghira/simpletuner/blob/main/simpletuner/cli/train.py"
click node_config "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/configuration/cmd_args.py"
click node_data "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/data_backend/factory.py"
click node_cache "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/caching/text_embeds.py"
click node_train "https://github.com/bghira/simpletuner/blob/main/simpletuner/__main__.py"
click node_dist "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/acceleration/backends.py"
click node_logging "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/logging.py"
click node_registry "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/models/all.py"
click node_model "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/models/sdxl/pipeline.py"
click node_adapters "https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/training/lycoris.py"
click node_webui "https://github.com/bghira/simpletuner/blob/main/simpletuner/static/js/sse-manager.js"
click node_server "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/app.py"
click node_configstore "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/config_store.py"
click node_inference "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/checkpoint_inference_service.py"
click node_process "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/process_keeper.py"
click node_workers "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/worker_manager.py"
click node_worker "https://github.com/bghira/simpletuner/blob/main/simpletuner/worker_agent.py"
click node_approval "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/cloud/approval/rules_engine.py"
click node_storage "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/routes/cloud/storage.py"
click node_storagebase "https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/cloud/storage/base.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_data,node_cache,node_train,node_dist,node_logging,node_user toneBlue
class node_registry,node_model,node_adapters toneAmber
class node_webui,node_server,node_configstore,node_inference,node_process toneMint
class node_workers,node_worker,node_approval,node_storage,node_storagebase toneRose
```

## Components

### Training runtime

- [CLI](https://github.com/bghira/simpletuner/blob/main/simpletuner/cli/train.py): `simpletuner/cli/train.py`
- [Configuration](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/configuration/cmd_args.py): `simpletuner/helpers/configuration/cmd_args.py`
- [Dataset backends](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/data_backend/factory.py): `simpletuner/helpers/data_backend/factory.py`
- [Embedding cache](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/caching/text_embeds.py): `simpletuner/helpers/caching/text_embeds.py`
- [Training runtime](https://github.com/bghira/simpletuner/blob/main/simpletuner/__main__.py): `simpletuner/__main__.py`
- [Distributed training](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/acceleration/backends.py): `simpletuner/helpers/acceleration/backends.py`
- [Logging](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/logging.py): `simpletuner/helpers/logging.py`

### Model support

- [Model registry](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/models/all.py): `simpletuner/helpers/models/all.py`
- [Model pipelines](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/models/sdxl/pipeline.py): `simpletuner/helpers/models/sdxl/pipeline.py`
- [LoRA and LyCORIS](https://github.com/bghira/simpletuner/blob/main/simpletuner/helpers/training/lycoris.py): `simpletuner/helpers/training/lycoris.py`

### Web interface

- [Web UI](https://github.com/bghira/simpletuner/blob/main/simpletuner/static/js/sse-manager.js): `simpletuner/static/js/sse-manager.js`
- [Server application](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/app.py): `simpletuner/simpletuner_sdk/server/app.py`
- [Config store](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/config_store.py): `simpletuner/simpletuner_sdk/server/services/config_store.py`
- [Checkpoint inference](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/checkpoint_inference_service.py): `simpletuner/simpletuner_sdk/server/services/checkpoint_inference_service.py`
- [Process manager](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/process_keeper.py): `simpletuner/simpletuner_sdk/process_keeper.py`

### Cloud platform

- [Worker orchestration](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/worker_manager.py): `simpletuner/simpletuner_sdk/server/services/worker_manager.py`
- [Worker agent](https://github.com/bghira/simpletuner/blob/main/simpletuner/worker_agent.py): `simpletuner/worker_agent.py`
- [Approval rules](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/cloud/approval/rules_engine.py): `simpletuner/simpletuner_sdk/server/services/cloud/approval/rules_engine.py`
- [Cloud storage API](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/routes/cloud/storage.py): `simpletuner/simpletuner_sdk/server/routes/cloud/storage.py`
- [Storage backend](https://github.com/bghira/simpletuner/blob/main/simpletuner/simpletuner_sdk/server/services/cloud/storage/base.py): `simpletuner/simpletuner_sdk/server/services/cloud/storage/base.py`

### Other components

- **User**

## Connections

- User → CLI: configures job (evidence: `README.md`)
- CLI → Configuration: loads settings
- Configuration → Dataset backends: selects datasets
- Dataset backends → Embedding cache: provides data
- Embedding cache → Training runtime: supplies embeddings
- Training runtime → Model registry: selects architecture
- Training runtime → Distributed training: uses sharding (evidence: `README.md`)
- Training runtime → LoRA and LyCORIS: trains adapters (evidence: `README.md`)
- Training runtime → Logging: emits logs
- Model registry → Model pipelines: selects pipeline
- User → Web UI: manages training (evidence: `README.md`)
- Web UI → Server application: sends requests
- Server application → Config store: loads configs (evidence: `simpletuner/simpletuner_sdk/server/app.py`)
- Server application → Process manager: starts jobs (evidence: `simpletuner/simpletuner_sdk/server/app.py`)
- Server application → Checkpoint inference: routes inference
- Checkpoint inference → Process manager: sends commands (evidence: `simpletuner/simpletuner_sdk/server/services/checkpoint_inference_service.py`)
- Server application → Worker orchestration: manages workers (evidence: `simpletuner/simpletuner_sdk/server/app.py`)
- Worker orchestration → Worker agent: dispatches jobs (evidence: `README.md`)
- Server application → Approval rules: evaluates approvals
- Worker agent → Cloud storage API: uploads artifacts (evidence: `README.md`)
- Cloud storage API → Storage backend: stores objects