# ggml-org/llamabarn architecture

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

- Interactive diagram: https://gitdiagram.com/ggml-org/llamabarn
- Repository: https://github.com/ggml-org/llamabarn

## Overview

Llama is a macOS menu-bar application for installing and running local GGUF language models through llama.cpp. The principal workflow is to discover or resolve a model, download it into the shared Hugging Face cache, register it as installed, and serve it locally for the built-in WebUI or API clients. The menu also manages server and model actions, while settings control server behavior, network exposure, and model overrides. The graph uses README statements and indexed or excerpted references; unsampled implementation details are not assumed.

Main entry points: [`Llama/Server/LlamaServer.swift`](https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/LlamaServer.swift) (llama.cpp Server), [`Llama/Downloads/ModelManager.swift`](https://github.com/ggml-org/llamabarn/blob/main/Llama/Downloads/ModelManager.swift) (Model Manager), [`Llama/Menu/MenuController.swift`](https://github.com/ggml-org/llamabarn/blob/main/Llama/Menu/MenuController.swift) (Menu Controller), [`Llama/Deeplinks/HFRepoResolver.swift`](https://github.com/ggml-org/llamabarn/blob/main/Llama/Deeplinks/HFRepoResolver.swift) (Hub Repo Resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Menu Bar App"]
  node_menu["Menu Controller"]
  node_actions["Model Actions"]
end

subgraph group_models["Model Discovery"]
  node_catalog["Featured Catalog<br/>[Catalog.swift]"]
  node_model["Model Records<br/>[Model.swift]"]
  node_idparser["Model ID Parser"]
end

subgraph group_install["Model Installation"]
  node_deeplink["Deep Link Handler"]
  node_resolver["Hub Repo Resolver"]
  node_hubfiles["Hub Metadata<br/>[HFRepoParser.swift]"]
  node_quant["GGUF Quantization<br/>[GGUFQuant.swift]"]
  node_downloads["Model Manager<br/>[ModelManager.swift]"]
  node_transfer["Download Transfer"]
  node_cache[("HF Cache<br/>[HFCache.swift]")]
end

subgraph group_runtime["Local Runtime"]
  node_installer["CLI Installer"]
  node_server["llama.cpp Server<br/>[LlamaServer.swift]"]
  node_serverapi["Server API Client"]
  node_clients(("WebUI and API Clients"))
end

subgraph group_control["Settings and Input"]
  node_overrides["Model Overrides"]
  node_settings["User Settings<br/>[UserSettings.swift]"]
  node_settingsui["Settings Window"]
  node_globalinput["Global Prompt Input"]
  node_network["Network Exposure Guard"]
end

node_user(("Mac User"))

node_user -->|"opens menu"| node_menu
node_menu -->|"fetches picks"| node_catalog
node_menu -->|"shows models"| node_downloads
node_menu -->|"shows status"| node_server
node_menu -->|"shows setup"| node_installer
node_menu -->|"delegates actions"| node_actions
node_actions -->|"manages models"| node_downloads
node_actions -->|"loads models"| node_server
node_catalog -->|"builds suggestions"| node_model
node_user -->|"opens model link"| node_deeplink
node_deeplink -->|"resolves repository"| node_resolver
node_deeplink -->|"starts download"| node_downloads
node_resolver -->|"parses repository"| node_hubfiles
node_resolver -->|"selects quant"| node_quant
node_resolver -->|"creates model"| node_model
node_downloads -->|"transfers files"| node_transfer
node_transfer -->|"writes cache"| node_cache
node_downloads -->|"scans models"| node_cache
node_downloads -->|"tracks installed"| node_model
node_downloads -->|"syncs model list"| node_server
node_installer -->|"starts when ready"| node_server
node_server -->|"reads model state"| node_downloads
node_server -->|"loads overrides"| node_overrides
node_server -->|"reads preferences"| node_settings
node_server -->|"uses API client"| node_serverapi
node_clients -->|"requests models"| node_server
node_server -->|"serves completions"| node_clients
node_user -->|"configures app"| node_settingsui
node_settingsui -->|"edits preferences"| node_settings
node_settingsui -->|"configures server"| node_server
node_settingsui -->|"controls exposure"| node_network
node_user -->|"captures prompt"| node_globalinput
node_globalinput -->|"selects installed model"| node_downloads
node_globalinput -->|"opens WebUI"| node_server
node_globalinput -->|"records model use"| node_settings

click node_menu "https://github.com/ggml-org/llamabarn/blob/main/Llama/Menu/MenuController.swift"
click node_actions "https://github.com/ggml-org/llamabarn/blob/main/Llama/Menu/ModelActionHandler.swift"
click node_catalog "https://github.com/ggml-org/llamabarn/blob/main/Llama/Catalog/Catalog.swift"
click node_model "https://github.com/ggml-org/llamabarn/blob/main/Llama/Models/Model.swift"
click node_idparser "https://github.com/ggml-org/llamabarn/blob/main/Llama/Models/ModelIdParser.swift"
click node_deeplink "https://github.com/ggml-org/llamabarn/blob/main/Llama/Deeplinks/DeeplinkHandler.swift"
click node_resolver "https://github.com/ggml-org/llamabarn/blob/main/Llama/Deeplinks/HFRepoResolver.swift"
click node_hubfiles "https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/HFRepoParser.swift"
click node_quant "https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/GGUFQuant.swift"
click node_downloads "https://github.com/ggml-org/llamabarn/blob/main/Llama/Downloads/ModelManager.swift"
click node_transfer "https://github.com/ggml-org/llamabarn/blob/main/Llama/Downloads/ModelManager%2BTransfer.swift"
click node_cache "https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/HFCache.swift"
click node_installer "https://github.com/ggml-org/llamabarn/blob/main/Llama/Engine/LlamaInstallManager.swift"
click node_server "https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/LlamaServer.swift"
click node_serverapi "https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/LlamaServerAPI.swift"
click node_overrides "https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/UserModelOverrides.swift"
click node_settings "https://github.com/ggml-org/llamabarn/blob/main/Llama/Settings/UserSettings.swift"
click node_settingsui "https://github.com/ggml-org/llamabarn/blob/main/Llama/Settings/SettingsWindow.swift"
click node_globalinput "https://github.com/ggml-org/llamabarn/blob/main/Llama/GlobalInput/GlobalInputController.swift"
click node_network "https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/NetworkExposureGuard.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_menu,node_actions,node_user toneBlue
class node_catalog,node_model,node_idparser toneAmber
class node_deeplink,node_resolver,node_hubfiles,node_quant,node_downloads,node_transfer,node_cache toneMint
class node_installer,node_server,node_serverapi,node_clients toneRose
class node_overrides,node_settings,node_settingsui,node_globalinput,node_network toneIndigo
```

## Components

### Menu Bar App

- [Menu Controller](https://github.com/ggml-org/llamabarn/blob/main/Llama/Menu/MenuController.swift): `Llama/Menu/MenuController.swift`
- [Model Actions](https://github.com/ggml-org/llamabarn/blob/main/Llama/Menu/ModelActionHandler.swift): `Llama/Menu/ModelActionHandler.swift`

### Model Discovery

- [Featured Catalog](https://github.com/ggml-org/llamabarn/blob/main/Llama/Catalog/Catalog.swift): `Llama/Catalog/Catalog.swift`
- [Model Records](https://github.com/ggml-org/llamabarn/blob/main/Llama/Models/Model.swift): `Llama/Models/Model.swift`
- [Model ID Parser](https://github.com/ggml-org/llamabarn/blob/main/Llama/Models/ModelIdParser.swift): `Llama/Models/ModelIdParser.swift`

### Model Installation

- [Deep Link Handler](https://github.com/ggml-org/llamabarn/blob/main/Llama/Deeplinks/DeeplinkHandler.swift): `Llama/Deeplinks/DeeplinkHandler.swift`
- [Hub Repo Resolver](https://github.com/ggml-org/llamabarn/blob/main/Llama/Deeplinks/HFRepoResolver.swift): `Llama/Deeplinks/HFRepoResolver.swift`
- [Hub Metadata](https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/HFRepoParser.swift): `Llama/HF/HFRepoParser.swift`
- [GGUF Quantization](https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/GGUFQuant.swift): `Llama/HF/GGUFQuant.swift`
- [Model Manager](https://github.com/ggml-org/llamabarn/blob/main/Llama/Downloads/ModelManager.swift): `Llama/Downloads/ModelManager.swift`
- [Download Transfer](https://github.com/ggml-org/llamabarn/blob/main/Llama/Downloads/ModelManager%2BTransfer.swift): `Llama/Downloads/ModelManager+Transfer.swift`
- [HF Cache](https://github.com/ggml-org/llamabarn/blob/main/Llama/HF/HFCache.swift): `Llama/HF/HFCache.swift`

### Local Runtime

- [CLI Installer](https://github.com/ggml-org/llamabarn/blob/main/Llama/Engine/LlamaInstallManager.swift): `Llama/Engine/LlamaInstallManager.swift`
- [llama.cpp Server](https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/LlamaServer.swift): `Llama/Server/LlamaServer.swift`
- [Server API Client](https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/LlamaServerAPI.swift): `Llama/Server/LlamaServerAPI.swift`
- **WebUI and API Clients**

### Settings and Input

- [Model Overrides](https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/UserModelOverrides.swift): `Llama/Server/UserModelOverrides.swift`
- [User Settings](https://github.com/ggml-org/llamabarn/blob/main/Llama/Settings/UserSettings.swift): `Llama/Settings/UserSettings.swift`
- [Settings Window](https://github.com/ggml-org/llamabarn/blob/main/Llama/Settings/SettingsWindow.swift): `Llama/Settings/SettingsWindow.swift`
- [Global Prompt Input](https://github.com/ggml-org/llamabarn/blob/main/Llama/GlobalInput/GlobalInputController.swift): `Llama/GlobalInput/GlobalInputController.swift`
- [Network Exposure Guard](https://github.com/ggml-org/llamabarn/blob/main/Llama/Server/NetworkExposureGuard.swift): `Llama/Server/NetworkExposureGuard.swift`

### Other components

- **Mac User**

## Connections

- Mac User → Menu Controller: opens menu (evidence: `Llama/Menu/MenuController.swift`)
- Menu Controller → Featured Catalog: fetches picks (evidence: `Llama/Menu/MenuController.swift`)
- Menu Controller → Model Manager: shows models (evidence: `Llama/Menu/MenuController.swift`)
- Menu Controller → llama.cpp Server: shows status (evidence: `Llama/Menu/MenuController.swift`)
- Menu Controller → CLI Installer: shows setup (evidence: `Llama/Menu/MenuController.swift`)
- Menu Controller → Model Actions: delegates actions (evidence: `Llama/Menu/MenuController.swift`)
- Model Actions → Model Manager: manages models (evidence: `Llama/Menu/ModelActionHandler.swift`)
- Model Actions → llama.cpp Server: loads models (evidence: `Llama/Menu/ModelActionHandler.swift`)
- Featured Catalog → Model Records: builds suggestions (evidence: `Llama/Catalog/Catalog.swift`)
- Mac User → Deep Link Handler: opens model link (evidence: `Llama/Deeplinks/DeeplinkHandler.swift`)
- Deep Link Handler → Hub Repo Resolver: resolves repository (evidence: `Llama/Deeplinks/DeeplinkHandler.swift`)
- Deep Link Handler → Model Manager: starts download (evidence: `Llama/Deeplinks/DeeplinkHandler.swift`)
- Hub Repo Resolver → Hub Metadata: parses repository (evidence: `Llama/Deeplinks/HFRepoResolver.swift`)
- Hub Repo Resolver → GGUF Quantization: selects quant (evidence: `Llama/Deeplinks/HFRepoResolver.swift`)
- Hub Repo Resolver → Model Records: creates model (evidence: `Llama/Deeplinks/HFRepoResolver.swift`)
- Model Manager → Download Transfer: transfers files (evidence: `Llama/Downloads/ModelManager.swift`)
- Download Transfer → HF Cache: writes cache (evidence: `Llama/Downloads/ModelManager+Transfer.swift`)
- Model Manager → HF Cache: scans models (evidence: `Llama/Downloads/ModelManager.swift`)
- Model Manager → Model Records: tracks installed (evidence: `Llama/Downloads/ModelManager.swift`)
- Model Manager → llama.cpp Server: syncs model list (evidence: `Llama/Downloads/ModelManager.swift`)
- CLI Installer → llama.cpp Server: starts when ready (evidence: `Llama/Engine/LlamaInstallManager.swift`)
- llama.cpp Server → Model Manager: reads model state (evidence: `Llama/Server/LlamaServer.swift`)
- llama.cpp Server → Model Overrides: loads overrides (evidence: `Llama/Server/LlamaServer.swift`)
- llama.cpp Server → User Settings: reads preferences (evidence: `Llama/Server/LlamaServer.swift`)
- llama.cpp Server → Server API Client: uses API client (evidence: `Llama/Server/LlamaServer.swift`)
- WebUI and API Clients → llama.cpp Server: requests models
- llama.cpp Server → WebUI and API Clients: serves completions
- Mac User → Settings Window: configures app (evidence: `Llama/Settings/SettingsWindow.swift`)
- Settings Window → User Settings: edits preferences (evidence: `Llama/Settings/SettingsWindow.swift`)
- Settings Window → llama.cpp Server: configures server (evidence: `Llama/Settings/SettingsWindow.swift`)
- Settings Window → Network Exposure Guard: controls exposure (evidence: `Llama/Settings/SettingsWindow.swift`)
- Mac User → Global Prompt Input: captures prompt (evidence: `Llama/GlobalInput/GlobalInputController.swift`)
- Global Prompt Input → Model Manager: selects installed model (evidence: `Llama/GlobalInput/GlobalInputController.swift`)
- Global Prompt Input → llama.cpp Server: opens WebUI (evidence: `Llama/GlobalInput/GlobalInputController.swift`)
- Global Prompt Input → User Settings: records model use (evidence: `Llama/GlobalInput/GlobalInputController.swift`)