# black-forest-labs/flux architecture

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

- Interactive diagram: https://gitdiagram.com/black-forest-labs/flux
- Repository: https://github.com/black-forest-labs/flux

## Overview

FLUX is a Python reference runtime for generating and editing images with open-weight models. Users invoke a command-line mode, provide text and—depending on the mode—an image, mask, or structural condition; the runtime prepares conditioning, samples the Flux model, decodes latents, and saves results. The README documents text-to-image, fill, structural conditioning, Redux variation, and Kontext editing. TensorRT is an optional inference backend. Relationships are limited to those shown in the README and supplied source references; unsampled implementation details are not inferred.

Main entry points: [`src/flux/sampling.py`](https://github.com/black-forest-labs/flux/blob/main/src/flux/sampling.py) (Sampling pipeline), [`src/flux/__main__.py`](https://github.com/black-forest-labs/flux/blob/main/src/flux/__main__.py) (Mode dispatch), [`src/flux/util.py`](https://github.com/black-forest-labs/flux/blob/main/src/flux/util.py) (Model and image utilities), [`src/flux/cli_kontext.py`](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_kontext.py) (Kontext editing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI modes"]
  node_dispatch["Mode dispatch<br/>[__main__.py]"]
  node_text["Text generation<br/>[cli.py]"]
  node_control["Structural control<br/>[cli_control.py]"]
  node_fill["Fill editing<br/>[cli_fill.py]"]
  node_kontext["Kontext editing<br/>[cli_kontext.py]"]
  node_redux["Redux variation<br/>[cli_redux.py]"]
end

subgraph group_conditioning["Inputs and conditioning"]
  node_text_encoders["Text encoders<br/>[conditioner.py]"]
  node_image_encoders["Image encoders<br/>[image_embedders.py]"]
end

subgraph group_inference["Model inference"]
  node_sampling["Sampling pipeline<br/>[sampling.py]"]
  node_autoencoder["Autoencoder<br/>[autoencoder.py]"]
  node_flux_model["Flux transformer<br/>[model.py]"]
  node_layers["Transformer layers<br/>[layers.py]"]
  node_math["Attention math<br/>[math.py]"]
  node_lora["LoRA support<br/>[lora.py]"]
end

subgraph group_output["Results and utilities"]
  node_filters["Content filters<br/>[content_filters.py]"]
  node_utilities["Model and image utilities<br/>[util.py]"]
end

subgraph group_tensorrt["TensorRT backend"]
  node_trt_manager["Engine manager<br/>[trt_manager.py]"]
  node_trt_configs["Engine configs"]
  node_trt_base["Engine runtime<br/>[base_engine.py]"]
  node_trt_transformer["Transformer engine"]
  node_trt_vae["VAE engines<br/>[vae_engine.py]"]
end

node_user(("User"))

node_user -->|"invokes"| node_dispatch
node_dispatch -->|"dispatches"| node_text
node_dispatch -->|"dispatches"| node_control
node_dispatch -->|"dispatches"| node_fill
node_dispatch -->|"dispatches"| node_kontext
node_dispatch -->|"dispatches"| node_redux
node_text -->|"calls"| node_sampling
node_control -->|"calls"| node_sampling
node_fill -->|"calls"| node_sampling
node_kontext -->|"calls"| node_sampling
node_redux -->|"calls"| node_sampling
node_sampling -->|"encodes prompts"| node_text_encoders
node_sampling -->|"encodes images"| node_image_encoders
node_sampling -->|"encodes and decodes"| node_autoencoder
node_sampling -->|"denoises with"| node_flux_model
node_sampling -->|"uses utilities"| node_utilities
node_flux_model -->|"uses layers"| node_layers
node_flux_model -->|"uses LoRA"| node_lora
node_layers -->|"uses attention math"| node_math
node_text -->|"loads and saves"| node_utilities
node_control -->|"uses utilities"| node_utilities
node_fill -->|"uses utilities"| node_utilities
node_kontext -->|"uses utilities"| node_utilities
node_kontext -->|"uses filters"| node_filters
node_redux -->|"uses utilities"| node_utilities
node_text -->|"loads engines"| node_trt_manager
node_control -->|"loads engines"| node_trt_manager
node_kontext -->|"loads engines"| node_trt_manager
node_trt_manager -->|"configures"| node_trt_configs
node_trt_manager -->|"loads engines"| node_trt_base
node_trt_transformer -->|"extends runtime"| node_trt_base
node_trt_vae -->|"extends runtime"| node_trt_base

click node_dispatch "https://github.com/black-forest-labs/flux/blob/main/src/flux/__main__.py"
click node_text "https://github.com/black-forest-labs/flux/blob/main/src/flux/cli.py"
click node_control "https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_control.py"
click node_fill "https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_fill.py"
click node_kontext "https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_kontext.py"
click node_redux "https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_redux.py"
click node_sampling "https://github.com/black-forest-labs/flux/blob/main/src/flux/sampling.py"
click node_text_encoders "https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/conditioner.py"
click node_image_encoders "https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/image_embedders.py"
click node_autoencoder "https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/autoencoder.py"
click node_flux_model "https://github.com/black-forest-labs/flux/blob/main/src/flux/model.py"
click node_layers "https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/layers.py"
click node_math "https://github.com/black-forest-labs/flux/blob/main/src/flux/math.py"
click node_lora "https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/lora.py"
click node_filters "https://github.com/black-forest-labs/flux/blob/main/src/flux/content_filters.py"
click node_utilities "https://github.com/black-forest-labs/flux/blob/main/src/flux/util.py"
click node_trt_manager "https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/trt_manager.py"
click node_trt_configs "https://github.com/black-forest-labs/flux/tree/main/src/flux/trt/trt_config"
click node_trt_base "https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/base_engine.py"
click node_trt_transformer "https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/transformer_engine.py"
click node_trt_vae "https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/vae_engine.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_dispatch,node_text,node_control,node_fill,node_kontext,node_redux,node_user toneBlue
class node_text_encoders,node_image_encoders toneAmber
class node_sampling,node_autoencoder,node_flux_model,node_layers,node_math,node_lora toneMint
class node_filters,node_utilities toneRose
class node_trt_manager,node_trt_configs,node_trt_base,node_trt_transformer,node_trt_vae toneIndigo
```

## Components

### CLI modes

- [Mode dispatch](https://github.com/black-forest-labs/flux/blob/main/src/flux/__main__.py): `src/flux/__main__.py`
- [Text generation](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli.py): `src/flux/cli.py`
- [Structural control](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_control.py): `src/flux/cli_control.py`
- [Fill editing](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_fill.py): `src/flux/cli_fill.py`
- [Kontext editing](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_kontext.py): `src/flux/cli_kontext.py`
- [Redux variation](https://github.com/black-forest-labs/flux/blob/main/src/flux/cli_redux.py): `src/flux/cli_redux.py`

### Inputs and conditioning

- [Text encoders](https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/conditioner.py): `src/flux/modules/conditioner.py`
- [Image encoders](https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/image_embedders.py): `src/flux/modules/image_embedders.py`

### Model inference

- [Sampling pipeline](https://github.com/black-forest-labs/flux/blob/main/src/flux/sampling.py): `src/flux/sampling.py`
- [Autoencoder](https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/autoencoder.py): `src/flux/modules/autoencoder.py`
- [Flux transformer](https://github.com/black-forest-labs/flux/blob/main/src/flux/model.py): `src/flux/model.py`
- [Transformer layers](https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/layers.py): `src/flux/modules/layers.py`
- [Attention math](https://github.com/black-forest-labs/flux/blob/main/src/flux/math.py): `src/flux/math.py`
- [LoRA support](https://github.com/black-forest-labs/flux/blob/main/src/flux/modules/lora.py): `src/flux/modules/lora.py`

### Results and utilities

- [Content filters](https://github.com/black-forest-labs/flux/blob/main/src/flux/content_filters.py): `src/flux/content_filters.py`
- [Model and image utilities](https://github.com/black-forest-labs/flux/blob/main/src/flux/util.py): `src/flux/util.py`

### TensorRT backend

- [Engine manager](https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/trt_manager.py): `src/flux/trt/trt_manager.py`
- [Engine configs](https://github.com/black-forest-labs/flux/tree/main/src/flux/trt/trt_config): `src/flux/trt/trt_config`
- [Engine runtime](https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/base_engine.py): `src/flux/trt/engine/base_engine.py`
- [Transformer engine](https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/transformer_engine.py): `src/flux/trt/engine/transformer_engine.py`
- [VAE engines](https://github.com/black-forest-labs/flux/blob/main/src/flux/trt/engine/vae_engine.py): `src/flux/trt/engine/vae_engine.py`

### Other components

- **User**

## Connections

- User → Mode dispatch: invokes (evidence: `src/flux/__main__.py`)
- Mode dispatch → Text generation: dispatches (evidence: `src/flux/__main__.py`)
- Mode dispatch → Structural control: dispatches (evidence: `src/flux/__main__.py`)
- Mode dispatch → Fill editing: dispatches (evidence: `src/flux/__main__.py`)
- Mode dispatch → Kontext editing: dispatches (evidence: `src/flux/__main__.py`)
- Mode dispatch → Redux variation: dispatches (evidence: `src/flux/__main__.py`)
- Text generation → Sampling pipeline: calls (evidence: `src/flux/cli.py`)
- Structural control → Sampling pipeline: calls (evidence: `src/flux/cli_control.py`)
- Fill editing → Sampling pipeline: calls (evidence: `src/flux/cli_fill.py`)
- Kontext editing → Sampling pipeline: calls (evidence: `src/flux/cli_kontext.py`)
- Redux variation → Sampling pipeline: calls (evidence: `src/flux/cli_redux.py`)
- Sampling pipeline → Text encoders: encodes prompts (evidence: `src/flux/sampling.py`)
- Sampling pipeline → Image encoders: encodes images (evidence: `src/flux/sampling.py`)
- Sampling pipeline → Autoencoder: encodes and decodes (evidence: `src/flux/sampling.py`)
- Sampling pipeline → Flux transformer: denoises with (evidence: `src/flux/sampling.py`)
- Sampling pipeline → Model and image utilities: uses utilities (evidence: `src/flux/sampling.py`)
- Flux transformer → Transformer layers: uses layers (evidence: `src/flux/model.py`)
- Flux transformer → LoRA support: uses LoRA (evidence: `src/flux/model.py`)
- Transformer layers → Attention math: uses attention math (evidence: `src/flux/modules/layers.py`)
- Text generation → Model and image utilities: loads and saves (evidence: `src/flux/cli.py`)
- Structural control → Model and image utilities: uses utilities (evidence: `src/flux/cli_control.py`)
- Fill editing → Model and image utilities: uses utilities (evidence: `src/flux/cli_fill.py`)
- Kontext editing → Model and image utilities: uses utilities (evidence: `src/flux/cli_kontext.py`)
- Kontext editing → Content filters: uses filters (evidence: `src/flux/cli_kontext.py`)
- Redux variation → Model and image utilities: uses utilities (evidence: `src/flux/cli_redux.py`)
- Text generation → Engine manager: loads engines (evidence: `src/flux/cli.py`)
- Structural control → Engine manager: loads engines (evidence: `src/flux/cli_control.py`)
- Kontext editing → Engine manager: loads engines (evidence: `src/flux/cli_kontext.py`)
- Engine manager → Engine configs: configures (evidence: `src/flux/trt/trt_manager.py`)
- Engine manager → Engine runtime: loads engines (evidence: `src/flux/trt/trt_manager.py`)
- Transformer engine → Engine runtime: extends runtime (evidence: `src/flux/trt/engine/transformer_engine.py`)
- VAE engines → Engine runtime: extends runtime (evidence: `src/flux/trt/engine/vae_engine.py`)
