# alexsjones/llmfit architecture

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

- Interactive diagram: https://gitdiagram.com/alexsjones/llmfit
- Repository: https://github.com/alexsjones/llmfit

## Overview

1. **What this repo is**
   - `llmfit` is a multi-surface Rust application for recommending LLMs for a machine’s hardware.
   - The same recommendation engine is exposed through several front ends: terminal TUI, classic CLI, HTTP API, background web dashboard, and a Tauri desktop app.

2. **Core architecture boundary**
   - `llmfit-core` is the central engine and is the main architectural boundary.
   - It owns model metadata, hardware detection, fit/scoring logic, provider integration, planning, benchmark handling, and update logic.
   - Every user-facing surface delegates to this crate rather than re-implementing model selection rules.

3. **Primary data flow**
   - Startup path is: detect hardware → load embedded model database → compute fit/speed/quality scores → rank models → render in UI/API output.
   - User actions such as filters, sort changes, hardware simulation, and advanced scoring changes all re-run the same core scoring pipeline against the current hardware state.

4. **Model knowledge layer**
   - The model catalog is a generated JSON dataset (`data/hf_models.json`, plus related baseline/cache files) that is embedded into the binary at build time.
   - A model update pipeline in `scripts/` scrapes Hugging Face and enriches entries with GGUF/provider metadata before regenerating the compiled-in database.
   - This means end users consume a static, versioned model database, while contributors refresh it offline.

5. **Hardware detection and estimation**
   - `hardware.rs` detects RAM, CPU cores, GPU presence, GPU memory, and backend type.
   - The engine supports multiple hardware families and uses that state to estimate whether a model fits and how fast it will run.
   - Hardware overrides and simulation are first-class inputs, so the recommendation engine can be run against synthetic targets as well as the real machine.

6. **Scoring / planning pipeline**
   - `fit.rs`, `quality.rs`, and `plan.rs` implement the main decision logic.
   - Models are scored across fit, speed, quality, and context dimensions, then ranked with use-case-specific weights.
   - The planning path inverts the analysis: given a model and target throughput/context, it estimates required hardware and upgrade deltas.

7. **Runtime/provider integration**
   - `providers.rs` is the adapter layer to local model runtimes and download sources.
   - It integrates with Ollama, llama.cpp, MLX, Docker Model Runner, and LM Studio for both installed-model detection and downloads.
   - Provider status feeds back into the table/UI, so “installed” and “download” actions are based on live runtime state, not just the static model catalog.

8. **Terminal product surface**
   - `llmfit-tui` is the main interactive app and uses `ratatui` + `crossterm`.
   - It owns TUI state, keyboard/event handling, filters, themeing, history, comparison views, download manager, and the in-app benchmark/leaderboard/plan views.
   - The TUI is essentially a stateful presentation layer over the core engine.

9. **CLI and HTTP API surface**
   - The same core logic is exposed in classic CLI mode via table/JSON output, and in `serve` mode as an HTTP API for automation/schedulers.
   - The API is meant for machine consumption: system info, filtered model lists, top recommendations, and planning data all come from the same scoring path used by the TUI.
   - This creates a clear separation between computation in `llmfit-core` and delivery formats in the front ends.

10. **Web dashboard**
   - The repo includes a separate web client in `llmfit-web` built with React/Vite.
   - It mirrors the model/system views of the terminal app and consumes the API layer rather than owning recommendation logic itself.
   - In architecture terms, it is a thin browser UI over the same backend data.

11. **Desktop packaging**
   - `llmfit-desktop` wraps the application in Tauri with a native shell and a small JS UI.
   - This is another presentation boundary, not a separate engine: the desktop app reuses the same core model/hardware/provider behavior through the Rust backend.

12. **Benchmarking and external data**
   - `bench.rs` and related files support live inference benchmarking against local providers, while the community leaderboard pulls real-world measurements from the external `localmaxxing.com` API.
   - These are distinct from the static model-fit estimator: one measures actual runtime behavior, the other queries crowd-sourced benchmark data.
   - Cached benchmark files under `data/` and `llmfit-core/data/` reduce repeated network calls and allow faster startup.

13. **Build, release, and packaging pipeline**
   - The repo is heavily automated with GitHub Actions, Docker, and release-please.
   - Rust artifacts are produced for CLI/TUI/core; the Python package in `llmfit-python` provides a separate distribution surface; Docker images expose JSON/CLI usage; Tauri builds the desktop app.
   - This is a multi-distribution project with one shared recommendation engine and several delivery targets.

14. **Auxiliary integrations**
   - The `skills/llmfit-advisor` directory packages an OpenClaw skill that calls the CLI as an external advisor.
   - `scripts/` also contains verification and scraping utilities, which are part of the maintenance/data-refresh boundary rather than runtime code.
   - These pieces reinforce that `llmfit` is both an application and a model-data pipeline.

Main entry points: [`llmfit-core/src/lib.rs`](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/lib.rs) (llmfit-core), [`llmfit-tui/src/serve_api.rs`](https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/serve_api.rs) (CLI/Serve), [`scripts/scrape_hf_models.py`](https://github.com/alexsjones/llmfit/blob/main/scripts/scrape_hf_models.py) (Scripts), [`data/hf_models.json`](https://github.com/alexsjones/llmfit/blob/main/data/hf_models.json) (Model data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_llmfit_core["llmfit-core<br/>engine crate<br/>[lib.rs]"]
  node_models["Models<br/>catalog<br/>[models.rs]"]
  node_hardware["Hardware<br/>detection<br/>[hardware.rs]"]
  node_fit(("Fit scoring<br/>ranking<br/>[fit.rs]"))
  node_quality(("Quality<br/>scoring<br/>[quality.rs]"))
  node_plan["Planning<br/>estimation<br/>[plan.rs]"]
  node_providers["Providers<br/>runtime adapter<br/>[providers.rs]"]
  node_bench["Benchmarking<br/>measurement<br/>[bench.rs]"]
  node_updates["Updates<br/>refresh<br/>[update.rs]"]
end

subgraph group_surfaces["User surfaces"]
  node_tui["llmfit-tui<br/>terminal app<br/>[tui_app.rs]"]
  node_cli_serve["CLI/Serve<br/>console + api<br/>[serve_api.rs]"]
  node_mcp["MCP server<br/>integration endpoint<br/>[mcp_server.rs]"]
  node_web["llmfit-web<br/>browser UI<br/>[App.jsx]"]
  node_desktop["llmfit-desktop<br/>tauri app<br/>[main.rs]"]
  node_python_pkg["llmfit-python<br/>python package<br/>[__init__.py]"]
end

subgraph group_data["Data pipeline"]
  node_model_data["Model data<br/>embedded datasets<br/>[hf_models.json]"]
  node_core_data["Core data<br/>embedded caches<br/>[hf_models.json]"]
  node_scripts["Scripts<br/>refresh pipeline"]
  node_leaderboard["Community data<br/>external api<br/>[benchmarks.rs]"]
end

subgraph group_dist["Distribution"]
  node_docker["Docker/Release<br/>packaging"]
  node_skill["Advisor skill<br/>external integration<br/>[SKILL.md]"]
end

node_tui -->|"uses engine"| node_llmfit_core
node_cli_serve -->|"queries"| node_llmfit_core
node_mcp -->|"advises via core"| node_llmfit_core
node_web -->|"calls API"| node_cli_serve
node_desktop -->|"backs UI"| node_llmfit_core
node_python_pkg -->|"wraps core"| node_llmfit_core
node_llmfit_core -->|"loads catalog"| node_models
node_llmfit_core -->|"detects target"| node_hardware
node_llmfit_core -->|"ranks fit"| node_fit
node_llmfit_core -->|"weights quality"| node_quality
node_llmfit_core -->|"inverts analysis"| node_plan
node_llmfit_core -->|"checks runtimes"| node_providers
node_llmfit_core -->|"benchmarks"| node_bench
node_llmfit_core -->|"refreshes data"| node_updates
node_scripts -->|"regenerates"| node_model_data
node_scripts -->|"updates caches"| node_core_data
node_model_data -->|"embedded into"| node_llmfit_core
node_core_data -->|"embedded into"| node_llmfit_core
node_leaderboard -->|"supplies results"| node_bench
node_docker -->|"packages"| node_cli_serve
node_skill -->|"invokes"| node_cli_serve

click node_llmfit_core "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/lib.rs"
click node_models "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/models.rs"
click node_hardware "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/hardware.rs"
click node_fit "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/fit.rs"
click node_quality "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/quality.rs"
click node_plan "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/plan.rs"
click node_providers "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/providers.rs"
click node_bench "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/bench.rs"
click node_updates "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/update.rs"
click node_tui "https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/tui_app.rs"
click node_cli_serve "https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/serve_api.rs"
click node_mcp "https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/mcp_server.rs"
click node_web "https://github.com/alexsjones/llmfit/blob/main/llmfit-web/src/App.jsx"
click node_desktop "https://github.com/alexsjones/llmfit/blob/main/llmfit-desktop/src/main.rs"
click node_python_pkg "https://github.com/alexsjones/llmfit/blob/main/llmfit-python/src/llmfit/__init__.py"
click node_model_data "https://github.com/alexsjones/llmfit/blob/main/data/hf_models.json"
click node_core_data "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/data/hf_models.json"
click node_scripts "https://github.com/alexsjones/llmfit/blob/main/scripts/scrape_hf_models.py"
click node_leaderboard "https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/benchmarks.rs"
click node_docker "https://github.com/alexsjones/llmfit/tree/main/Dockerfile"
click node_skill "https://github.com/alexsjones/llmfit/blob/main/skills/llmfit-advisor/SKILL.md"

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_llmfit_core,node_models,node_hardware,node_fit,node_quality,node_plan,node_providers,node_bench,node_updates toneBlue
class node_tui,node_cli_serve,node_mcp,node_web,node_desktop,node_python_pkg toneAmber
class node_model_data,node_core_data,node_scripts,node_leaderboard toneMint
class node_docker,node_skill toneRose
```

## Components

### Core engine

Shared recommendation logic and model knowledge.

- [llmfit-core](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/lib.rs): engine crate · Central recommendation engine shared by every surface. · `llmfit-core/src/lib.rs`
- [Models](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/models.rs): catalog · Embedded model metadata and dataset loading. · `llmfit-core/src/models.rs`
- [Hardware](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/hardware.rs): detection · Detects RAM, CPU, GPU, backend, and override/simulated state. · `llmfit-core/src/hardware.rs`
- [Fit scoring](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/fit.rs): ranking · Computes fit and speed scores against current hardware. · `llmfit-core/src/fit.rs`
- [Quality](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/quality.rs): scoring · Adds quality and context-oriented scoring signals. · `llmfit-core/src/quality.rs`
- [Planning](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/plan.rs): estimation · Inverts scoring to estimate required hardware and upgrade deltas. · `llmfit-core/src/plan.rs`
- [Providers](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/providers.rs): runtime adapter · Integrates Ollama, llama.cpp, MLX, Docker Model Runner, and LM Studio. · `llmfit-core/src/providers.rs`
- [Benchmarking](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/bench.rs): measurement · Live inference benchmarking and leaderboard support. · `llmfit-core/src/bench.rs`
- [Updates](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/update.rs): refresh · Model refresh and update logic for the embedded database. · `llmfit-core/src/update.rs`

### User surfaces

Interfaces that present the same engine in different forms.

- [llmfit-tui](https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/tui_app.rs): terminal app · Interactive TUI shell over the shared engine. · `llmfit-tui/src/tui_app.rs`
- [CLI/Serve](https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/serve_api.rs): console + api · Table/JSON output and HTTP API mode for automation. · `llmfit-tui/src/serve_api.rs`
- [MCP server](https://github.com/alexsjones/llmfit/blob/main/llmfit-tui/src/mcp_server.rs): integration endpoint · External assistant-facing control surface. · `llmfit-tui/src/mcp_server.rs`
- [llmfit-web](https://github.com/alexsjones/llmfit/blob/main/llmfit-web/src/App.jsx): browser UI · React/Vite dashboard that consumes the HTTP API. · `llmfit-web/src/App.jsx`
- [llmfit-desktop](https://github.com/alexsjones/llmfit/blob/main/llmfit-desktop/src/main.rs): tauri app · Native desktop shell around the shared Rust backend. · `llmfit-desktop/src/main.rs`
- [llmfit-python](https://github.com/alexsjones/llmfit/blob/main/llmfit-python/src/llmfit/__init__.py): python package · Separate Python distribution surface for the same toolchain. · `llmfit-python/src/llmfit/__init__.py`

### Data pipeline

Generated model datasets, benchmarks, and refresh tooling.

- [Model data](https://github.com/alexsjones/llmfit/blob/main/data/hf_models.json): embedded datasets · Generated Hugging Face, benchmark, and baseline JSON/YAML inputs. · `data/hf_models.json`
- [Core data](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/data/hf_models.json): embedded caches · Crate-local datasets used by the engine and startup cache paths. · `llmfit-core/data/hf_models.json`
- [Scripts](https://github.com/alexsjones/llmfit/blob/main/scripts/scrape_hf_models.py): refresh pipeline · Scrapers, validators, and model-generation utilities. · `scripts/scrape_hf_models.py`
- [Community data](https://github.com/alexsjones/llmfit/blob/main/llmfit-core/src/benchmarks.rs): external api · Crowd-sourced benchmark source used for leaderboard views. · `llmfit-core/src/benchmarks.rs`

### Distribution

Packaging and release targets around the shared Rust workspace.

- [Docker/Release](https://github.com/alexsjones/llmfit/tree/main/Dockerfile): packaging · Container, release-please, and CI automation for multiple targets. · `Dockerfile`
- [Advisor skill](https://github.com/alexsjones/llmfit/blob/main/skills/llmfit-advisor/SKILL.md): external integration · OpenClaw skill that shells out to the CLI as an advisor. · `skills/llmfit-advisor/SKILL.md`

## Connections

- llmfit-tui → llmfit-core: uses engine · Interactive presentation delegates recommendation work to the core crate.
- CLI/Serve → llmfit-core: queries · CLI and HTTP API reuse the same scoring and planning pipeline.
- MCP server → llmfit-core: advises via core · Assistant integration accesses the same shared backend logic.
- llmfit-web → CLI/Serve: calls API · Browser UI consumes the serve mode rather than reimplementing logic.
- llmfit-desktop → llmfit-core: backs UI · Tauri shell wraps the Rust engine and presentation bridge.
- llmfit-python → llmfit-core: wraps core · Python distribution mirrors the same engine as a separate package.
- llmfit-core → Models: loads catalog · Engine starts by loading embedded model metadata.
- llmfit-core → Hardware: detects target · Hardware state is the main input to fit and planning.
- llmfit-core → Fit scoring: ranks fit · Fit scoring drives ranked recommendations.
- llmfit-core → Quality: weights quality · Quality signals contribute to overall ranking.
- llmfit-core → Planning: inverts analysis · Planning estimates hardware needs from a target model and throughput.
- llmfit-core → Providers: checks runtimes · Runtime integration informs installed/download state.
- llmfit-core → Benchmarking: benchmarks · Live benchmark support feeds benchmark and leaderboard views.
- llmfit-core → Updates: refreshes data · Update logic regenerates or refreshes the embedded database.
- Scripts → Model data: regenerates · Scrapers and validators produce the versioned model datasets.
- Scripts → Core data: updates caches · Maintenance scripts refresh crate-local cache and baseline files.
- Model data → llmfit-core: embedded into · Generated datasets are compiled into the application.
- Core data → llmfit-core: embedded into · Core crate consumes local cached datasets at build/runtime.
- Community data → Benchmarking: supplies results · External benchmark source powers community leaderboard views.
- Docker/Release → CLI/Serve: packages · Container and release automation target the CLI/API surface.
- Advisor skill → CLI/Serve: invokes · The advisor skill shells out to the CLI as an external tool.
