pwilkin/catapult

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.