# pwilkin/catapult architecture

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

- Interactive diagram: https://gitdiagram.com/pwilkin/catapult
- Repository: https://github.com/pwilkin/catapult

## Overview

1. **Overall shape**
   - Catapult is a desktop launcher with two user-facing shells over the same Rust core: a **GUI** built with **Tauri v2 + React/TypeScript** (`src/`) and a **TUI** built with **ratatui/crossterm** (`src-tauri/src/tui`).
   - The GUI runs inside the Tauri webview and talks to Rust through Tauri IPC; the TUI bypasses the web layer and drives the same backend modules directly.

2. **Backend boundary**
   - The Rust side is the system-of-record for anything that touches the machine: downloading runtimes/models, reading hardware, launching/stopping subprocesses, and persisting settings/presets.
   - The key shared backend modules are `hardware.rs`, `runtime.rs`, `models.rs`, `server.rs`, `huggingface.rs`, and `config.rs`, with `lib.rs`/`main.rs` wiring the app entrypoints.

3. **GUI presentation layer**
   - The React app is organized by domain screens: `Dashboard`, `Runtime`, `Models`, `Server`, `Chat`, and `Wizard`.
   - `Layout.tsx` and shared components provide the chrome/navigation, while page components mostly render state and dispatch actions into the Tauri backend.

4. **TUI presentation layer**
   - The terminal app is split into tabs that mirror the GUI’s core workflows: dashboard, runtime, models, server, logs, and chat.
   - `app.rs`, `event.rs`, and `server_ctl.rs` manage the TUI event loop and backend interaction; tab-specific logic lives under `src-tauri/src/tui/tabs/`.

5. **Runtime management subsystem**
   - `runtime.rs` handles llama.cpp runtime discovery, version management, activation, and likely download/install orchestration.
   - The app supports both **managed runtimes** pulled from GitHub releases and **custom local runtimes**, with hardware-aware backend scoring from `hardware.rs` to recommend CUDA/Metal/ROCm/Vulkan/CPU builds.

6. **Model management subsystem**
   - `models.rs` and `huggingface.rs` cover model discovery, metadata parsing, recommended-model listings, and downloads.
   - Models are discovered from local directories, with GGUF metadata read from file headers; downloads come from HuggingFace with resume/retry behavior, and vision models get mmproj pairing support.

7. **Server configuration and process control**
   - `server.rs` is the main boundary for constructing and managing the `llama-server` process.
   - The GUI exposes configuration through tabbed parameter groups; the TUI exposes the same underlying flags through autocomplete-driven parameter editing.
   - Presets are first-class: named configurations can be saved/loaded, and model selection can recall the last-used preset.

8. **Execution and log flow**
   - Launching the server produces a long-running subprocess whose output is streamed back into the UI.
   - The TUI has a dedicated logs tab for this stream; the GUI surfaces status and controls from the dashboard/server views.
   - Stopping, restarting, and aborting downloads are explicit lifecycle controls in both interfaces.

9. **Chat subsystem**
   - The chat experience is not a separate backend service; it is another process/UI mode built on top of the selected model and server settings.
   - In the GUI, chat is embedded via the llama.cpp WebUI in an iframe and can be popped out to a separate window.
   - In the TUI, chat launches `llama-cli` as a subprocess and returns control when it exits.

10. **Persistence and local state**
    - State appears to be file-based rather than database-backed: runtime installs, model files, presets, and configuration live on disk in user-controlled locations.
    - `config.rs` and the Tauri app configuration define the app’s local settings and permissions boundary, while the Rust backend mediates all filesystem and process access.

11. **First-launch and system discovery**
    - The GUI includes a wizard that combines hardware detection, runtime recommendation, and model selection to get to a working setup quickly.
    - This is a good diagram boundary to show: hardware info feeds recommendations, recommendations feed runtime/model choices, and those choices feed server launch.

12. **External dependencies**
    - The app depends on **GitHub Releases** for managed llama.cpp binaries and **HuggingFace** for model discovery/download.
    - It also orchestrates external local executables from the llama.cpp ecosystem: `llama-server`, the WebUI, and `llama-cli`.

13. **Useful diagram summary**
    - A good architecture diagram would show three layers: **presentation** (GUI/TUI), **Rust backend services** (hardware/runtime/models/server/config), and **external/local execution targets** (filesystem, GitHub, HuggingFace, llama.cpp subprocesses).
    - The main data flows are: hardware detection → runtime/model recommendation → download/install → server configuration → subprocess launch → log/chat output back to UI.

Main entry points: [`src-tauri/src/server.rs`](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/server.rs) (Server manager), [`src-tauri/src/runtime.rs`](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/runtime.rs) (Runtime manager), [`src-tauri/src/models.rs`](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/models.rs) (Model manager), [`src/App.tsx`](https://github.com/pwilkin/catapult/blob/master/src/App.tsx) (GUI shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_gui_shell["GUI shell<br/>tauri react shell<br/>[App.tsx]"]
  node_gui_dashboard["Dashboard<br/>gui page<br/>[Dashboard.tsx]"]
  node_gui_runtime["Runtime<br/>gui page<br/>[Runtime.tsx]"]
  node_gui_models["Models<br/>gui page<br/>[Models.tsx]"]
  node_gui_server["Server<br/>gui page<br/>[Server.tsx]"]
  node_gui_chat["Chat<br/>gui page<br/>[Chat.tsx]"]
  node_gui_wizard["Wizard<br/>gui page<br/>[Wizard.tsx]"]
  node_tui_app["TUI shell<br/>terminal app<br/>[app.rs]"]
  node_tui_tabs["TUI tabs<br/>terminal views<br/>[mod.rs]"]
  node_tui_server_ctl["TUI server ctl<br/>terminal control<br/>[server_ctl.rs]"]
  node_tui_params["TUI params<br/>autocomplete ui<br/>[params.rs]"]
end

subgraph group_backend["Rust backend"]
  node_app_entry["App entry<br/>tauri bootstrap<br/>[main.rs]"]
  node_config["Config<br/>settings state<br/>[config.rs]"]
  node_hardware["Hardware<br/>device probe<br/>[hardware.rs]"]
  node_runtime["Runtime manager<br/>llama.cpp runtime<br/>[runtime.rs]"]
  node_models["Model manager<br/>model discovery<br/>[models.rs]"]
  node_server["Server manager<br/>process orchestrator<br/>[server.rs]"]
  node_huggingface["Hugging Face<br/>model source client<br/>[huggingface.rs]"]
end

subgraph group_external["External targets"]
  node_filesystem[("Local files<br/>disk state")]
  node_github_releases[("GitHub releases<br/>binary source")]
  node_llama_execs["llama.cpp tools<br/>subprocesses"]
end

node_gui_shell -->|"navigates"| node_gui_dashboard
node_gui_shell -->|"navigates"| node_gui_runtime
node_gui_shell -->|"navigates"| node_gui_models
node_gui_shell -->|"navigates"| node_gui_server
node_gui_shell -->|"navigates"| node_gui_chat
node_gui_shell -->|"navigates"| node_gui_wizard
node_tui_app -->|"renders"| node_tui_tabs
node_tui_app -->|"drives"| node_tui_server_ctl
node_tui_app -->|"edits"| node_tui_params
node_app_entry -->|"loads"| node_config
node_app_entry -->|"starts"| node_hardware
node_app_entry -->|"wires"| node_runtime
node_app_entry -->|"wires"| node_models
node_app_entry -->|"wires"| node_server
node_hardware -->|"recommends"| node_runtime
node_hardware -->|"recommends"| node_models
node_runtime -->|"downloads"| node_github_releases
node_runtime -->|"installs"| node_filesystem
node_models -->|"queries"| node_huggingface
node_models -->|"reads"| node_filesystem
node_huggingface -->|"stores"| node_filesystem
node_server -->|"uses"| node_runtime
node_server -->|"uses"| node_models
node_server -->|"applies"| node_config
node_server -->|"spawns"| node_llama_execs
node_gui_chat -->|"spawns"| node_llama_execs
node_tui_tabs -->|"controls"| node_server
node_gui_wizard -->|"reads"| node_hardware
node_gui_wizard -->|"selects"| node_runtime
node_gui_wizard -->|"selects"| node_models
node_gui_server -->|"configures"| node_server
node_gui_models -->|"manages"| node_models
node_gui_runtime -->|"manages"| node_runtime
node_gui_dashboard -->|"monitors"| node_server

click node_gui_shell "https://github.com/pwilkin/catapult/blob/master/src/App.tsx"
click node_gui_dashboard "https://github.com/pwilkin/catapult/blob/master/src/pages/Dashboard.tsx"
click node_gui_runtime "https://github.com/pwilkin/catapult/blob/master/src/pages/Runtime.tsx"
click node_gui_models "https://github.com/pwilkin/catapult/blob/master/src/pages/Models.tsx"
click node_gui_server "https://github.com/pwilkin/catapult/blob/master/src/pages/Server.tsx"
click node_gui_chat "https://github.com/pwilkin/catapult/blob/master/src/pages/Chat.tsx"
click node_gui_wizard "https://github.com/pwilkin/catapult/blob/master/src/pages/Wizard.tsx"
click node_tui_app "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/app.rs"
click node_tui_tabs "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/tabs/mod.rs"
click node_tui_server_ctl "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/server_ctl.rs"
click node_tui_params "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/params.rs"
click node_app_entry "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/main.rs"
click node_config "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/config.rs"
click node_hardware "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/hardware.rs"
click node_runtime "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/runtime.rs"
click node_models "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/models.rs"
click node_server "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/server.rs"
click node_huggingface "https://github.com/pwilkin/catapult/blob/master/src-tauri/src/huggingface.rs"

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_gui_shell,node_gui_dashboard,node_gui_runtime,node_gui_models,node_gui_server,node_gui_chat,node_gui_wizard,node_tui_app,node_tui_tabs,node_tui_server_ctl,node_tui_params toneBlue
class node_app_entry,node_config,node_hardware,node_runtime,node_models,node_server,node_huggingface toneAmber
class node_filesystem,node_github_releases,node_llama_execs toneMint
```

## Components

### Presentation

GUI and TUI shells that drive the app

- [GUI shell](https://github.com/pwilkin/catapult/blob/master/src/App.tsx): tauri react shell · Tauri webview app and shared chrome/navigation · `src/App.tsx`
- [Dashboard](https://github.com/pwilkin/catapult/blob/master/src/pages/Dashboard.tsx): gui page · Status and quick actions · `src/pages/Dashboard.tsx`
- [Runtime](https://github.com/pwilkin/catapult/blob/master/src/pages/Runtime.tsx): gui page · Runtime discovery and selection · `src/pages/Runtime.tsx`
- [Models](https://github.com/pwilkin/catapult/blob/master/src/pages/Models.tsx): gui page · Model browsing and downloads · `src/pages/Models.tsx`
- [Server](https://github.com/pwilkin/catapult/blob/master/src/pages/Server.tsx): gui page · Server configuration and controls · `src/pages/Server.tsx`
- [Chat](https://github.com/pwilkin/catapult/blob/master/src/pages/Chat.tsx): gui page · Embedded chat and pop-out view · `src/pages/Chat.tsx`
- [Wizard](https://github.com/pwilkin/catapult/blob/master/src/pages/Wizard.tsx): gui page · First-launch setup flow · `src/pages/Wizard.tsx`
- [TUI shell](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/app.rs): terminal app · Terminal UI event loop and screen management · `src-tauri/src/tui/app.rs`
- [TUI tabs](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/tabs/mod.rs): terminal views · Dashboard, runtime, models, server, logs, and chat tabs · `src-tauri/src/tui/tabs/mod.rs`
- [TUI server ctl](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/server_ctl.rs): terminal control · Server lifecycle and backend interaction for the TUI · `src-tauri/src/tui/server_ctl.rs`
- [TUI params](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/tui/params.rs): autocomplete ui · Parameter editing and autocomplete widgets · `src-tauri/src/tui/params.rs`

### Rust backend

Shared system-of-record services and process orchestration

- [App entry](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/main.rs): tauri bootstrap · Rust entrypoints and app wiring · `src-tauri/src/main.rs`
- [Config](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/config.rs): settings state · Local settings, presets, and app configuration · `src-tauri/src/config.rs`
- [Hardware](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/hardware.rs): device probe · System detection and hardware-aware scoring · `src-tauri/src/hardware.rs`
- [Runtime manager](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/runtime.rs): llama.cpp runtime · Runtime discovery, versioning, activation, and install orchestration · `src-tauri/src/runtime.rs`
- [Model manager](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/models.rs): model discovery · Local model discovery, metadata, and model selection · `src-tauri/src/models.rs`
- [Server manager](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/server.rs): process orchestrator · Constructs and runs the llama-server process · `src-tauri/src/server.rs`
- [Hugging Face](https://github.com/pwilkin/catapult/blob/master/src-tauri/src/huggingface.rs): model source client · Model catalog and download client · `src-tauri/src/huggingface.rs`

### External targets

Local state, package sources, and spawned executables

- **Local files**: disk state · Runtime installs, model files, presets, and configuration on disk
- **GitHub releases**: binary source · Managed runtime release source
- **llama.cpp tools**: subprocesses · llama-server, llama-cli, and WebUI executables

## Connections

- GUI shell → Dashboard: navigates · Shared UI chrome routes users across domain pages
- GUI shell → Runtime: navigates · Routes to runtime management
- GUI shell → Models: navigates · Routes to model management
- GUI shell → Server: navigates · Routes to server configuration
- GUI shell → Chat: navigates · Routes to chat mode
- GUI shell → Wizard: navigates · Routes to first-launch setup
- TUI shell → TUI tabs: renders · Manages tabbed terminal views
- TUI shell → TUI server ctl: drives · Coordinates backend actions and lifecycle events
- TUI shell → TUI params: edits · Uses autocomplete-driven parameter entry
- App entry → Config: loads · Initializes local configuration and permissions
- App entry → Hardware: starts · Bootstraps hardware discovery
- App entry → Runtime manager: wires · Connects runtime service into the app
- App entry → Model manager: wires · Connects model service into the app
- App entry → Server manager: wires · Connects server control into the app
- Hardware → Runtime manager: recommends · Hardware profile informs runtime build selection
- Hardware → Model manager: recommends · Hardware profile informs model suggestions
- Runtime manager → GitHub releases: downloads · Managed runtimes are fetched from releases
- Runtime manager → Local files: installs · Runtime binaries and metadata live on disk
- Model manager → Hugging Face: queries · Remote catalog and downloads come from Hugging Face
- Model manager → Local files: reads · Discovers local model files and GGUF metadata
- Hugging Face → Local files: stores · Downloaded models are persisted locally
- Server manager → Runtime manager: uses · Server launch depends on the selected runtime
- Server manager → Model manager: uses · Server launch depends on the selected model
- Server manager → Config: applies · Presets and named settings shape server flags
- Server manager → llama.cpp tools: spawns · Runs llama-server and related tools as subprocesses
- Chat → llama.cpp tools: spawns · Chat uses llama.cpp WebUI or CLI execution paths
- TUI tabs → Server manager: controls · Server tab and logs tab reflect backend process state
- Wizard → Hardware: reads · First-launch setup begins with system discovery
- Wizard → Runtime manager: selects · Wizard helps choose an appropriate runtime
- Wizard → Model manager: selects · Wizard helps choose an initial model
- Server → Server manager: configures · Server page edits flags, presets, and launch settings
- Models → Model manager: manages · Model page triggers discovery and downloads
- Runtime → Runtime manager: manages · Runtime page triggers install and activation
- Dashboard → Server manager: monitors · Dashboard surfaces server state and lifecycle controls