# lllyasviel/fooocus architecture

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

- Interactive diagram: https://gitdiagram.com/lllyasviel/fooocus
- Repository: https://github.com/lllyasviel/fooocus

## Overview

#### Purpose and Execution

Fooocus is a local/offline Python application for prompt- and image-guided SDXL image generation, exposed through a Gradio UI. Primary launch paths are `entry_with_update.py` (installation/update-aware launcher), `launch.py` (runtime bootstrap), and `webui.py` (UI assembly/server). Docker alternatives are `Dockerfile`, `docker-compose.yml`, and `entrypoint.sh`.

#### Startup, Arguments, and Configuration

CLI flags, hardware mode, networking, preset selection, paths, and precision policy enter through `args_manager.py` and are propagated into shared runtime state via `shared.py`. Configuration resolves model/output directories and defaults, while presets define model/style behavior. Core paths: `modules/config.py`, `presets/default.json`, `modules/launch_util.py`.

The process is designed to download missing model assets on demand; local model directories under `models/` are the durable artifact boundary.

#### Browser UI and Request Boundary

`webui.py` constructs the Gradio interface, integrating custom UI behavior from `modules/gradio_hijack.py`, `modules/ui_gradio_extensions.py`, and browser assets in `javascript/` and `css/`. It collects prompts, styles, generation settings, uploaded images/masks, and preset changes; it may bind locally, listen remotely, or use Gradio share endpoints. Optional basic authentication is handled by `modules/auth.py`.

#### Asynchronous Generation Orchestration

The UI submits work to a long-lived asynchronous worker rather than performing inference in request callbacks. `modules/async_worker.py` is the principal queue/control boundary between interactive Gradio events and GPU-intensive execution. It coordinates request modes—text-to-image, image variation/upscale, inpaint/outpaint, and image-prompt conditioning—then returns previews/results to the UI. `modules/private_logger.py` owns result logging/output handling.

#### Prompt, Style, and Input Preparation

Before diffusion, requests are expanded and normalized: styles and SDXL prompt formatting are managed by `modules/sdxl_styles.py`; wildcard/inline prompt handling is supported by `modules/util.py`; Fooocus’s model-backed prompt expansion is in `extras/expansion.py`. Image-driven operations prepare masks, crops, adapters, and preprocessing through `modules/inpaint_worker.py`, `extras/inpaint_mask.py`, and `extras/preprocessors.py`.

This stage converts user-facing inputs into prompts, latent/image conditions, masks, and model selections consumed by the pipeline.

#### Diffusion Pipeline and Model Lifecycle

`modules/default_pipeline.py` is the application-level SDXL pipeline, with model loading and selection through `modules/model_loader.py` and `modules/core.py`. It bridges application semantics to the vendored/patched inference engine in `ldm_patched/`, including checkpoint loading, LoRA application, sampling, ControlNet, and VRAM management. Key engine paths: `ldm_patched/modules/sd.py`, `ldm_patched/modules/sample.py`, `ldm_patched/modules/model_management.py`.

The primary flow is: prepared request → load/patch base/refiner/LoRA/control models as needed → encode conditions and initialize latents → iterative sampler execution → decode image → return/save output.

#### Extensions, Safety, and Deployment Constraints

Optional enrichment and postprocessing are local ML integrations: image interrogation/captioning (`extras/interrogate.py`, vendored `extras/BLIP/`), face processing (`extras/face_crop.py`), image-prompt adapters (`extras/ip_adapter.py`), and safety checking (`extras/safety_checker/models/safety_checker.py`). Grounding and segmentation assets are vendored under `extras/GroundingDINO/` and `extras/sam/`.

Runtime is Python/PyTorch with CUDA as the primary target; DirectML, ROCm, MPS, and CPU modes are supported through launch/runtime options. Model downloads rely on Hugging Face-hosted artifacts; public sharing relies on Gradio’s `.gradio.live` service.

Main entry points: [`webui.py`](https://github.com/lllyasviel/fooocus/blob/main/webui.py) (Gradio Web UI), [`modules/default_pipeline.py`](https://github.com/lllyasviel/fooocus/blob/main/modules/default_pipeline.py) (SDXL application pipeline), [`modules/async_worker.py`](https://github.com/lllyasviel/fooocus/blob/main/modules/async_worker.py) (Async generation worker), [`modules/config.py`](https://github.com/lllyasviel/fooocus/blob/main/modules/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup &amp; Configuration"]
  node_launcher["Launchers<br/>Python entrypoints"]
  node_args["Arguments &amp; shared state<br/>runtime options<br/>[args_manager.py]"]
  node_config["Configuration<br/>config resolver<br/>[config.py]"]
  node_preset["Default preset<br/>[default.json]"]
end

subgraph group_ui["Interactive UI"]
  node_webui["Gradio Web UI<br/>UI server<br/>[webui.py]"]
  node_ui_extensions["UI customizations<br/>Gradio/browser extensions<br/>[gradio_hijack.py]"]
  node_auth["Basic authentication<br/>access control<br/>[auth.py]"]
end

subgraph group_orchestration["Request Preparation"]
  node_async_worker["Async generation worker<br/>work queue<br/>[async_worker.py]"]
  node_prompt_prep["Prompt &amp; style preparation<br/>conditioning prep<br/>[sdxl_styles.py]"]
  node_image_prep["Image input preparation<br/>conditioning prep<br/>[inpaint_worker.py]"]
end

subgraph group_inference["Inference Runtime"]
  node_pipeline["SDXL application pipeline<br/>diffusion pipeline"]
  node_model_loader["Model lifecycle<br/>model loader<br/>[model_loader.py]"]
  node_patched_engine["Patched inference engine<br/>SDXL engine"]
end

subgraph group_artifacts["Artifacts &amp; Integrations"]
  node_model_store[("Local model store<br/>durable artifacts")]
  node_output_logger["Output logging<br/>result handler<br/>[private_logger.py]"]
  node_optional_ml["Optional ML enrichments<br/>local integrations<br/>[interrogate.py]"]
  node_model_downloads[("Hugging Face artifacts<br/>external model source")]
  node_gradio_share(("Gradio share service<br/>external sharing"))
end

node_launcher -->|"parses runtime options"| node_args
node_args -->|"configures"| node_config
node_preset -->|"provides defaults"| node_config
node_config -->|"initializes"| node_webui
node_webui -->|"extends with"| node_ui_extensions
node_auth -.->|"protects"| node_webui
node_webui -->|"submits generation jobs"| node_async_worker
node_webui -.->|"optionally publishes through"| node_gradio_share
node_async_worker -->|"prepares prompts"| node_prompt_prep
node_async_worker -->|"prepares image conditions"| node_image_prep
node_prompt_prep -->|"conditions request"| node_pipeline
node_image_prep -->|"supplies masks and adapters"| node_pipeline
node_async_worker -->|"orchestrates modes"| node_pipeline
node_pipeline -->|"selects required models"| node_model_loader
node_model_loader -->|"loads local assets"| node_model_store
node_model_downloads -.->|"downloads missing assets"| node_model_store
node_pipeline -->|"executes inference"| node_patched_engine
node_optional_ml -.->|"optional enrichment"| node_async_worker
node_pipeline -->|"returns generated images"| node_output_logger
node_output_logger -->|"streams previews and results"| node_webui

click node_launcher "https://github.com/lllyasviel/fooocus/blob/main/entry_with_update.py"
click node_args "https://github.com/lllyasviel/fooocus/blob/main/args_manager.py"
click node_config "https://github.com/lllyasviel/fooocus/blob/main/modules/config.py"
click node_preset "https://github.com/lllyasviel/fooocus/blob/main/presets/default.json"
click node_webui "https://github.com/lllyasviel/fooocus/blob/main/webui.py"
click node_ui_extensions "https://github.com/lllyasviel/fooocus/blob/main/modules/gradio_hijack.py"
click node_auth "https://github.com/lllyasviel/fooocus/blob/main/modules/auth.py"
click node_async_worker "https://github.com/lllyasviel/fooocus/blob/main/modules/async_worker.py"
click node_prompt_prep "https://github.com/lllyasviel/fooocus/blob/main/modules/sdxl_styles.py"
click node_image_prep "https://github.com/lllyasviel/fooocus/blob/main/modules/inpaint_worker.py"
click node_pipeline "https://github.com/lllyasviel/fooocus/blob/main/modules/default_pipeline.py"
click node_model_loader "https://github.com/lllyasviel/fooocus/blob/main/modules/model_loader.py"
click node_output_logger "https://github.com/lllyasviel/fooocus/blob/main/modules/private_logger.py"
click node_optional_ml "https://github.com/lllyasviel/fooocus/blob/main/extras/interrogate.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_launcher,node_args,node_config,node_preset toneBlue
class node_webui,node_ui_extensions,node_auth toneAmber
class node_async_worker,node_prompt_prep,node_image_prep toneMint
class node_pipeline,node_model_loader,node_patched_engine toneRose
class node_model_store,node_output_logger,node_optional_ml,node_model_downloads,node_gradio_share toneIndigo
```

## Components

### Startup & Configuration

- [Launchers](https://github.com/lllyasviel/fooocus/blob/main/entry_with_update.py): Python entrypoints · Update-aware and runtime bootstrap paths start the application. · `entry_with_update.py`
- [Arguments & shared state](https://github.com/lllyasviel/fooocus/blob/main/args_manager.py): runtime options · CLI, hardware, network, preset, and precision choices become shared runtime state. · `args_manager.py`
- [Configuration](https://github.com/lllyasviel/fooocus/blob/main/modules/config.py): config resolver · Resolves model/output locations and defaults. · `modules/config.py`
- [Default preset](https://github.com/lllyasviel/fooocus/blob/main/presets/default.json): preset · Defines default model and style behavior. · `presets/default.json`

### Interactive UI

- [Gradio Web UI](https://github.com/lllyasviel/fooocus/blob/main/webui.py): UI server · Collects prompts, settings, images, masks, and preset changes. · `webui.py`
- [UI customizations](https://github.com/lllyasviel/fooocus/blob/main/modules/gradio_hijack.py): Gradio/browser extensions · Custom Gradio behavior and browser assets extend the interface. · `modules/gradio_hijack.py`
- [Basic authentication](https://github.com/lllyasviel/fooocus/blob/main/modules/auth.py): access control · Optional authentication for the UI server. · `modules/auth.py`

### Request Preparation

- [Async generation worker](https://github.com/lllyasviel/fooocus/blob/main/modules/async_worker.py): work queue · Long-lived control boundary between UI events and GPU execution. · `modules/async_worker.py`
- [Prompt & style preparation](https://github.com/lllyasviel/fooocus/blob/main/modules/sdxl_styles.py): conditioning prep · Expands, normalizes, and formats prompts and styles. · `modules/sdxl_styles.py`
- [Image input preparation](https://github.com/lllyasviel/fooocus/blob/main/modules/inpaint_worker.py): conditioning prep · Builds masks, crops, adapters, and preprocessed image conditions. · `modules/inpaint_worker.py`

### Inference Runtime

- [SDXL application pipeline](https://github.com/lllyasviel/fooocus/blob/main/modules/default_pipeline.py): diffusion pipeline · Selects models, encodes conditions, samples latents, and decodes images. · `modules/default_pipeline.py`
- [Model lifecycle](https://github.com/lllyasviel/fooocus/blob/main/modules/model_loader.py): model loader · Loads and selects checkpoints, refiners, LoRAs, and control models. · `modules/model_loader.py`
- **Patched inference engine**: SDXL engine · Provides checkpoint loading, sampling, ControlNet, and VRAM management.

### Artifacts & Integrations

- **Local model store**: durable artifacts · Persistent boundary for downloaded model assets.
- [Output logging](https://github.com/lllyasviel/fooocus/blob/main/modules/private_logger.py): result handler · Saves and logs generated results. · `modules/private_logger.py`
- [Optional ML enrichments](https://github.com/lllyasviel/fooocus/blob/main/extras/interrogate.py): local integrations · Captioning, face processing, IP adapters, safety, grounding, and segmentation. · `extras/interrogate.py`
- **Hugging Face artifacts**: external model source · Supplies missing model assets on demand.
- **Gradio share service**: external sharing · Optional public UI endpoint.

## Connections

- Launchers → Arguments & shared state: parses runtime options
- Arguments & shared state → Configuration: configures
- Default preset → Configuration: provides defaults
- Configuration → Gradio Web UI: initializes
- Gradio Web UI → UI customizations: extends with
- Basic authentication → Gradio Web UI: protects
- Gradio Web UI → Async generation worker: submits generation jobs
- Gradio Web UI → Gradio share service: optionally publishes through
- Async generation worker → Prompt & style preparation: prepares prompts
- Async generation worker → Image input preparation: prepares image conditions
- Prompt & style preparation → SDXL application pipeline: conditions request
- Image input preparation → SDXL application pipeline: supplies masks and adapters
- Async generation worker → SDXL application pipeline: orchestrates modes
- SDXL application pipeline → Model lifecycle: selects required models
- Model lifecycle → Local model store: loads local assets
- Hugging Face artifacts → Local model store: downloads missing assets
- SDXL application pipeline → Patched inference engine: executes inference
- Optional ML enrichments → Async generation worker: optional enrichment
- SDXL application pipeline → Output logging: returns generated images
- Output logging → Gradio Web UI: streams previews and results
