# Core Components of the llmfit Rust Workspace: A Deep Dive into the Cargo Architecture

> Explore the core components of the llmfit Rust workspace. Understand the Cargo architecture including llmfit-core, llmfit-tui, and llmfit-desktop for your development.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: deep-dive
- Published: 2026-09-13

---

**The llmfit Rust workspace is organized as a Cargo workspace comprising three primary crates: `llmfit-core` (shared library containing business logic), `llmfit-tui` (CLI and terminal UI binary with HTTP API), and `llmfit-desktop` (optional Tauri-based desktop application).**

The `AlexsJones/llmfit` repository delivers hardware-aware LLM model matching, benchmarking, and deployment planning tools. Understanding the core components of the llmfit Rust workspace enables developers to embed its analysis engine in custom tools, extend the CLI functionality, or contribute to the hardware detection algorithms.

## The Three Primary Crates

The workspace root defines three member crates with distinct responsibilities, ensuring clean separation between library logic and presentation layers.

### llmfit-core: The Shared Library Engine

**`llmfit-core`** is the foundational library crate that implements all business logic for hardware detection, model catalog management, and fit analysis. Located in [`llmfit-core/src/lib.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/lib.rs), this crate exposes the public API that all other workspace members consume. It handles CPU and GPU enumeration via the `sysinfo` crate, parses the embedded Hugging Face model catalog ([`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json)), and calculates quantitative fit scores for hardware-model compatibility.

Key modules within this crate include [`hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/hardware.rs) and [`hwprofile.rs`](https://github.com/AlexsJones/llmfit/blob/main/hwprofile.rs) for system introspection, [`models.rs`](https://github.com/AlexsJones/llmfit/blob/main/models.rs) for the model database, and [`analysis.rs`](https://github.com/AlexsJones/llmfit/blob/main/analysis.rs) paired with [`fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/fit.rs) for the core fitting algorithms. The library also provides benchmarking capabilities through [`bench.rs`](https://github.com/AlexsJones/llmfit/blob/main/bench.rs) and [`benchmarks.rs`](https://github.com/AlexsJones/llmfit/blob/main/benchmarks.rs), quality assessment via [`quality.rs`](https://github.com/AlexsJones/llmfit/blob/main/quality.rs), and Kubernetes integration through [`plan.rs`](https://github.com/AlexsJones/llmfit/blob/main/plan.rs) and [`claim.rs`](https://github.com/AlexsJones/llmfit/blob/main/claim.rs).

### llmfit-tui: Interactive Terminal Interface

**`llmfit-tui`** produces the main `llmfit` binary, serving as the primary user-facing entry point. The crate's entry point at [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) uses `clap` for argument parsing and dispatches to either traditional CLI output or the interactive terminal UI built with **ratatui**.

This crate aggregates functionality from multiple submodules: [`tui_app.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_app.rs) manages application state and model filtering, [`tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_ui.rs) handles stateless rendering of tables and pop-ups, and [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_events.rs) processes the input event loop. Additionally, `llmfit-tui` exposes the core functionality over network protocols via [`serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/serve_api.rs) (Axum HTTP API) and [`mcp_server.rs`](https://github.com/AlexsJones/llmfit/blob/main/mcp_server.rs) (stdin/stdout Model Context Protocol server), enabling external tooling integration without direct library linking.

### llmfit-desktop: Optional Native Desktop Wrapper

**`llmfit-desktop`** provides an optional Tauri-based desktop application that wraps the core library in a native UI. The entry point at [`llmfit-desktop/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-desktop/src/main.rs) forwards hardware detection commands, fit analysis requests, and model download operations to `llmfit-core`, presenting results through a webview-based interface. This crate demonstrates how the core library can be embedded in cross-platform GUI applications while maintaining the same analysis engine used by the terminal interface.

## Architectural Deep Dive into llmfit-core

The `llmfit-core` crate organizes functionality into specialized modules that work together to provide comprehensive LLM deployment analysis.

### Hardware Detection and Profiling

System introspection begins in [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs) and [`llmfit-core/src/hwprofile.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hwprofile.rs). These modules use the `sysinfo` crate to collect CPU specifications, RAM capacity, GPU availability (including unified memory detection on Apple Silicon), and available disk space. The `SystemSpecs::detect()` function returns a comprehensive hardware profile that downstream modules use to evaluate model feasibility.

### Model Database Management

The model catalog resides in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs), which loads an embedded JSON database ([`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json)) generated by [`scripts/scrape_hf_models.py`](https://github.com/AlexsJones/llmfit/blob/main/scripts/scrape_hf_models.py). This module defines the `Model` struct, capturing metadata such as parameter count, quantization levels, VRAM requirements, and provider information. The `ModelDatabase::new()` constructor initializes this catalog for querying during fit analysis.

### Fit Analysis and Scoring Engine

The heart of the system lives in [`llmfit-core/src/analysis.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/analysis.rs) and [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs). The `build_model_fits()` function orchestrates the evaluation of every model in the catalog against detected hardware capabilities. It calculates memory usage projections, throughput estimates, and assigns quantitative fit scores. The analysis determines appropriate runtimes (GPU acceleration, CPU fallback, or layer offloading strategies) and filters results based on user constraints like "perfect fit" mode.

### Benchmarking and Quality Assessment

[`llmfit-core/src/bench.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/bench.rs) and [`llmfit-core/src/benchmarks.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/benchmarks.rs) implement local and remote endpoint testing, measuring actual tokens-per-second throughput against theoretical predictions. The [`llmfit-core/src/quality.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/quality.rs) module adds response quality evaluation capabilities, allowing users to assess model output correctness alongside raw performance metrics.

### Planning and Kubernetes Integration

For deployment scenarios, [`llmfit-core/src/plan.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/plan.rs) estimates memory and throughput for specific model configurations, helping operators plan resource allocation. The [`llmfit-core/src/claim.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/claim.rs) module extends this by generating Kubernetes Dynamic Resource Allocation (DRA) claim manifests, enabling automated hardware provisioning in containerized environments.

## Interface Layer: CLI, TUI, and API

The `llmfit-tui` crate implements three distinct interaction modes, all delegating to `llmfit-core` for data processing.

### Command-Line Parsing and Dispatch

The main entry point in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) parses CLI flags using `clap`, supporting subcommands like `fit`, `bench`, and `serve`. Based on arguments, it either prints tabular or JSON output via [`display.rs`](https://github.com/AlexsJones/llmfit/blob/main/display.rs) or launches the interactive interface. The implementation avoids `unwrap` on user-provided paths, following the project's safety conventions using a shared `Result` type.

### Ratatui Interactive Interface

When invoked with `--tui`, the application initializes `tui_app::App`, which maintains the state of selected models, active filters, and scroll positions. The rendering logic in [`tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_ui.rs) draws bordered tables, model detail panes, and confirmation pop-ups, while [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_events.rs) handles keyboard navigation and resize events.

### HTTP API and MCP Server

[`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs) exposes an Axum-based HTTP REST API that returns hardware profiles and model fits as JSON, enabling integration with external dashboards or scripts. The [`llmfit-tui/src/mcp_server.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/mcp_server.rs) implements a lightweight stdin/stdout protocol (Model Context Protocol), allowing AI assistants to query hardware compatibility programmatically.

## Working with the Workspace

You can interact with the core components through various entry points depending on your use case.

### Running CLI Analysis

Execute the "perfect-fit" mode to display the top five models matching your hardware:

```bash
cargo run --release -- fit --perfect -n 5

```

This command triggers the full analysis pipeline: `SystemSpecs::detect()` → `ModelDatabase::new()` → `build_model_fits()`.

### Using llmfit-core Programmatically

Embed the library in your Rust application to perform custom analysis:

```rust
use llmfit_core::{hardware::SystemSpecs, models::ModelDatabase, analysis::build_model_fits};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Detect hardware
    let specs = SystemSpecs::detect()?;

    // Load the model catalog
    let db = ModelDatabase::new()?;

    // Compute fits
    let fits = build_model_fits(&specs, &db, None)?;

    // Print the best fit
    if let Some(best) = fits.first() {
        println!("Best model: {}", best.model.name);
    }
    Ok(())
}

```

### Launching the Interactive TUI

Start the ratatui-based interface for interactive filtering and inspection:

```bash
cargo run -- --tui

```

The binary starts `tui_app::App`, which loads core analysis results and hands control to the ratatui event loop defined in [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_events.rs).

## Summary

- The **llmfit Rust workspace** follows a three-crate architecture: `llmfit-core` (library), `llmfit-tui` (CLI/TUI binary), and `llmfit-desktop` (optional GUI).
- **`llmfit-core`** contains all business logic in modules like [`hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/hardware.rs), [`models.rs`](https://github.com/AlexsJones/llmfit/blob/main/models.rs), and [`analysis.rs`](https://github.com/AlexsJones/llmfit/blob/main/analysis.rs), exposing a safe public API through [`lib.rs`](https://github.com/AlexsJones/llmfit/blob/main/lib.rs).
- **`llmfit-tui`** provides multiple interfaces: traditional CLI output, interactive ratatui terminal UI, Axum HTTP API, and MCP server protocol.
- **Hardware detection** leverages the `sysinfo` crate in [`hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/hardware.rs) and [`hwprofile.rs`](https://github.com/AlexsJones/llmfit/blob/main/hwprofile.rs), while **fit analysis** centralizes in [`analysis.rs`](https://github.com/AlexsJones/llmfit/blob/main/analysis.rs) and [`fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/fit.rs).
- The workspace supports **benchmarking** ([`bench.rs`](https://github.com/AlexsJones/llmfit/blob/main/bench.rs)), **quality testing** ([`quality.rs`](https://github.com/AlexsJones/llmfit/blob/main/quality.rs)), and **Kubernetes integration** ([`claim.rs`](https://github.com/AlexsJones/llmfit/blob/main/claim.rs)) for production deployments.
- All components share consistent error handling using a custom `Result` type and avoid unsafe unwrapping on user inputs.

## Frequently Asked Questions

### What is the relationship between llmfit-core and llmfit-tui?

**`llmfit-core`** is a reusable library crate containing all algorithms and data structures, while **`llmfit-tui`** is a binary crate that depends on `llmfit-core` to provide user interfaces. The TUI crate handles CLI argument parsing, terminal rendering, and network protocols, delegating all hardware detection and model analysis to function calls into the core library. This separation allows other applications (like `llmfit-desktop`) to import the same logic without pulling in terminal-specific dependencies.

### How does llmfit detect hardware capabilities?

The hardware detection system in [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs) uses the `sysinfo` crate to query CPU core counts, clock speeds, and RAM capacity. For GPU detection, it examines system buses to identify NVIDIA, AMD, and Apple Silicon devices, calculating available VRAM and unified memory. The `SystemSpecs::detect()` method aggregates this information into a `HwProfile` struct defined in [`hwprofile.rs`](https://github.com/AlexsJones/llmfit/blob/main/hwprofile.rs), which the fit analysis engine uses to determine model compatibility and runtime selection strategies.

### Can I use llmfit-core as a standalone library?

Yes, `llmfit-core` is designed as a standalone library crate with a public API exported from [`llmfit-core/src/lib.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/lib.rs). You can add it as a dependency in your [`Cargo.toml`](https://github.com/AlexsJones/llmfit/blob/main/Cargo.toml) and import modules like `hardware`, `models`, and `analysis` to perform programmatic hardware detection and model fitting. The crate includes no terminal or UI dependencies, making it suitable for embedding in web servers, automation scripts, or other GUI frameworks beyond the provided Tauri implementation.

### What protocols does llmfit-tui support for external integration?

The `llmfit-tui` crate exposes core functionality through two primary protocols: an **HTTP REST API** implemented in [`serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/serve_api.rs) using the Axum framework, which returns JSON representations of hardware specs and model fits; and an **MCP (Model Context Protocol) server** in [`mcp_server.rs`](https://github.com/AlexsJones/llmfit/blob/main/mcp_server.rs) that communicates over stdin/stdout. These interfaces allow external tools, AI assistants, and web dashboards to query the llmfit analysis engine without linking the Rust library directly or parsing terminal output.