# rinste/turbo-mlx architecture

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

- Interactive diagram: https://gitdiagram.com/rinste/turbo-mlx
- Repository: https://github.com/rinste/turbo-mlx

## Overview

Turbo MLX is a local Apple-Silicon generative-media app. A user configures a model and prompt, downloads model files when needed, submits generation through the app’s backend process, and reviews or reuses results in history. The engine supports image creation and editing, video, audio, and upscaling through model-family implementations. README capabilities and indexed module references establish the broad subsystem map; sampled excerpts show only selected call paths, so unverified engine-to-family dispatch is omitted.

Main entry points: [`Engine/Sources/TurboEngineCore/Engine.swift`](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Engine.swift) (Engine runtime), [`TurboMLX/App/AppModel.swift`](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/App/AppModel.swift) (App coordinator), [`TurboMLX/Services/BackendController.swift`](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/BackendController.swift) (Worker controller), [`Engine/Sources/TurboEngineCore/Families/Shared/Qwen3Prompter.swift`](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/Shared/Qwen3Prompter.swift) (Prompt tokenization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["macOS App"]
  node_ui["Generation controls<br/>[ControlPanel.swift]"]
  node_appmodel["App coordinator<br/>[AppModel.swift]"]
  node_results["Results viewer<br/>[OutputPanel.swift]"]
  node_historyui["History browser<br/>[HistoryStrip.swift]"]
  node_history[("History store<br/>[HistoryStore.swift]")]
end

subgraph group_models["Model Management"]
  node_catalog["Model catalog<br/>[ModelCatalog.swift]"]
  node_downloads["Model downloads"]
  node_hub["Hub access"]
  node_locator["Model locator<br/>[ModelLocator.swift]"]
  node_lora["LoRA library<br/>[LoRALibrary.swift]"]
end

subgraph group_engine["Generation Engine"]
  node_backend["Worker controller"]
  node_protocol["Worker protocol"]
  node_process["Line process<br/>[LineProcess.swift]"]
  node_enginecore["Engine runtime<br/>[Engine.swift]"]
  node_checkpoint["Checkpoint loading<br/>[Checkpoint.swift]"]
  node_prompt["Prompt tokenization"]
  node_loraapply["LoRA adapters<br/>[LoRAAdapters.swift]"]
end

subgraph group_media["Media Workflows"]
  node_image["Image generation"]
  node_editing["Image editing"]
  node_video["Video generation<br/>[LTXPipeline.swift]"]
  node_upscale["Image upscaling"]
  node_audio["Audio generation"]
  node_outputs["Media output<br/>[ImageOutput.swift]"]
  node_preview["Live preview"]
end

node_user(("Mac user"))
node_huggingface["Model hub"]

node_user -->|"configures"| node_ui
node_ui -->|"updates settings"| node_appmodel
node_appmodel -->|"selects model"| node_catalog
node_appmodel -->|"starts downloads"| node_downloads
node_downloads -.->|"downloads from"| node_hub
node_huggingface -->|"serves models"| node_hub
node_appmodel -->|"locates model"| node_locator
node_appmodel -->|"sends jobs"| node_backend
node_backend -->|"starts process"| node_process
node_backend -->|"sends commands"| node_protocol
node_backend -->|"forwards events"| node_appmodel
node_appmodel -->|"manages LoRAs"| node_lora
node_enginecore -.->|"loads weights"| node_checkpoint
node_enginecore -->|"applies adapters"| node_loraapply
node_enginecore -->|"writes image"| node_outputs
node_enginecore -.->|"generates images"| node_image
node_enginecore -.->|"runs edits"| node_editing
node_enginecore -.->|"generates video"| node_video
node_enginecore -.->|"upscales images"| node_upscale
node_enginecore -.->|"generates audio"| node_audio
node_editing -.->|"uses prompt"| node_prompt
node_image -.->|"tokenizes prompt"| node_prompt
node_video -.->|"tokenizes prompt"| node_prompt
node_enginecore -.->|"emits previews"| node_preview
node_appmodel -->|"stores results"| node_history
node_historyui -.->|"browses items"| node_history
node_historyui -.->|"selects result"| node_results
node_results -->|"shows media"| node_user

click node_ui "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/ControlPanel.swift"
click node_appmodel "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/App/AppModel.swift"
click node_results "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/OutputPanel.swift"
click node_historyui "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/HistoryStrip.swift"
click node_history "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/HistoryStore.swift"
click node_catalog "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Models/ModelCatalog.swift"
click node_downloads "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/DownloadCenter.swift"
click node_hub "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/HubDownloader.swift"
click node_locator "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/ModelLocator.swift"
click node_lora "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/LoRALibrary.swift"
click node_backend "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/BackendController.swift"
click node_protocol "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/WorkerProtocol.swift"
click node_process "https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/LineProcess.swift"
click node_enginecore "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Engine.swift"
click node_checkpoint "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Checkpoint.swift"
click node_prompt "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/Shared/Qwen3Prompter.swift"
click node_loraapply "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/LoRA/LoRAAdapters.swift"
click node_image "https://github.com/rinste/turbo-mlx/tree/main/Engine/Sources/TurboEngineCore/Families"
click node_editing "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/QwenImage/QwenImageEditPipeline.swift"
click node_video "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/LTX/LTXPipeline.swift"
click node_upscale "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/SeedVR2/SeedVR2Pipeline.swift"
click node_audio "https://github.com/rinste/turbo-mlx/tree/main/Engine/Sources/TurboEngineCore/Families/MiniMaxMusic3"
click node_outputs "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/ImageOutput.swift"
click node_preview "https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/Shared/LatentPreview.swift"

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_ui,node_appmodel,node_results,node_historyui,node_history,node_user toneBlue
class node_catalog,node_downloads,node_hub,node_locator,node_lora toneAmber
class node_backend,node_protocol,node_process,node_enginecore,node_checkpoint,node_prompt,node_loraapply toneMint
class node_image,node_editing,node_video,node_upscale,node_audio,node_outputs,node_preview toneRose
class node_huggingface toneIndigo
```

## Components

### macOS App

- [Generation controls](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/ControlPanel.swift): `TurboMLX/Views/ControlPanel.swift`
- [App coordinator](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/App/AppModel.swift): `TurboMLX/App/AppModel.swift`
- [Results viewer](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/OutputPanel.swift): `TurboMLX/Views/OutputPanel.swift`
- [History browser](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Views/HistoryStrip.swift): `TurboMLX/Views/HistoryStrip.swift`
- [History store](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/HistoryStore.swift): `TurboMLX/Services/HistoryStore.swift`

### Model Management

- [Model catalog](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Models/ModelCatalog.swift): `TurboMLX/Models/ModelCatalog.swift`
- [Model downloads](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/DownloadCenter.swift): `TurboMLX/Services/DownloadCenter.swift`
- [Hub access](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/HubDownloader.swift): `TurboMLX/Services/HubDownloader.swift`
- [Model locator](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/ModelLocator.swift): `TurboMLX/Services/ModelLocator.swift`
- [LoRA library](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/LoRALibrary.swift): `TurboMLX/Services/LoRALibrary.swift`

### Generation Engine

- [Worker controller](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/BackendController.swift): `TurboMLX/Services/BackendController.swift`
- [Worker protocol](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/WorkerProtocol.swift): `TurboMLX/Services/WorkerProtocol.swift`
- [Line process](https://github.com/rinste/turbo-mlx/blob/main/TurboMLX/Services/LineProcess.swift): `TurboMLX/Services/LineProcess.swift`
- [Engine runtime](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Engine.swift): `Engine/Sources/TurboEngineCore/Engine.swift`
- [Checkpoint loading](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Checkpoint.swift): `Engine/Sources/TurboEngineCore/Checkpoint.swift`
- [Prompt tokenization](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/Shared/Qwen3Prompter.swift): `Engine/Sources/TurboEngineCore/Families/Shared/Qwen3Prompter.swift`
- [LoRA adapters](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/LoRA/LoRAAdapters.swift): `Engine/Sources/TurboEngineCore/LoRA/LoRAAdapters.swift`

### Media Workflows

- [Image generation](https://github.com/rinste/turbo-mlx/tree/main/Engine/Sources/TurboEngineCore/Families): `Engine/Sources/TurboEngineCore/Families`
- [Image editing](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/QwenImage/QwenImageEditPipeline.swift): `Engine/Sources/TurboEngineCore/Families/QwenImage/QwenImageEditPipeline.swift`
- [Video generation](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/LTX/LTXPipeline.swift): `Engine/Sources/TurboEngineCore/Families/LTX/LTXPipeline.swift`
- [Image upscaling](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/SeedVR2/SeedVR2Pipeline.swift): `Engine/Sources/TurboEngineCore/Families/SeedVR2/SeedVR2Pipeline.swift`
- [Audio generation](https://github.com/rinste/turbo-mlx/tree/main/Engine/Sources/TurboEngineCore/Families/MiniMaxMusic3): `Engine/Sources/TurboEngineCore/Families/MiniMaxMusic3`
- [Media output](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/ImageOutput.swift): `Engine/Sources/TurboEngineCore/ImageOutput.swift`
- [Live preview](https://github.com/rinste/turbo-mlx/blob/main/Engine/Sources/TurboEngineCore/Families/Shared/LatentPreview.swift): `Engine/Sources/TurboEngineCore/Families/Shared/LatentPreview.swift`

### Other components

- **Mac user**
- **Model hub**

## Connections

- Mac user → Generation controls: configures (evidence: `README.md`)
- Generation controls → App coordinator: updates settings (evidence: `TurboMLX/Views/ControlPanel.swift`)
- App coordinator → Model catalog: selects model (evidence: `TurboMLX/App/AppModel.swift`)
- App coordinator → Model downloads: starts downloads (evidence: `TurboMLX/App/AppModel.swift`)
- Model downloads → Hub access: downloads from (evidence: `TurboMLX/Services/DownloadCenter.swift`)
- Model hub → Hub access: serves models (evidence: `README.md`)
- App coordinator → Model locator: locates model (evidence: `TurboMLX/App/AppModel.swift`)
- App coordinator → Worker controller: sends jobs (evidence: `TurboMLX/App/AppModel.swift`)
- Worker controller → Line process: starts process (evidence: `TurboMLX/Services/BackendController.swift`)
- Worker controller → Worker protocol: sends commands (evidence: `TurboMLX/Services/BackendController.swift`)
- Worker controller → App coordinator: forwards events (evidence: `TurboMLX/Services/BackendController.swift`)
- App coordinator → LoRA library: manages LoRAs (evidence: `TurboMLX/App/AppModel.swift`)
- Engine runtime → Checkpoint loading: loads weights
- Engine runtime → LoRA adapters: applies adapters (evidence: `Engine/Sources/TurboEngineCore/Engine.swift`)
- Engine runtime → Media output: writes image (evidence: `Engine/Sources/TurboEngineCore/Engine.swift`)
- Engine runtime → Image generation: generates images (evidence: `Engine/Sources/TurboEngineCore/Engine.swift`)
- Engine runtime → Image editing: runs edits
- Engine runtime → Video generation: generates video
- Engine runtime → Image upscaling: upscales images
- Engine runtime → Audio generation: generates audio
- Image editing → Prompt tokenization: uses prompt (evidence: `Engine/Sources/TurboEngineCore/Families/QwenImage/QwenImageEditPipeline.swift`)
- Image generation → Prompt tokenization: tokenizes prompt (evidence: `Engine/Sources/TurboEngineCore/Families/LTX/LTXPipeline.swift`)
- Video generation → Prompt tokenization: tokenizes prompt (evidence: `Engine/Sources/TurboEngineCore/Families/LTX/LTXPipeline.swift`)
- Engine runtime → Live preview: emits previews
- App coordinator → History store: stores results (evidence: `TurboMLX/App/AppModel.swift`)
- History browser → History store: browses items
- History browser → Results viewer: selects result (evidence: `TurboMLX/Views/OutputPanel.swift`)
- Results viewer → Mac user: shows media (evidence: `README.md`)
