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

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, 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), and calculates quantitative fit scores for hardware-model compatibility.

Key modules within this crate include hardware.rs and hwprofile.rs for system introspection, models.rs for the model database, and analysis.rs paired with fit.rs for the core fitting algorithms. The library also provides benchmarking capabilities through bench.rs and benchmarks.rs, quality assessment via quality.rs, and Kubernetes integration through plan.rs and 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 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 manages application state and model filtering, tui_ui.rs handles stateless rendering of tables and pop-ups, and tui_events.rs processes the input event loop. Additionally, llmfit-tui exposes the core functionality over network protocols via serve_api.rs (Axum HTTP API) and 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 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 and 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, which loads an embedded JSON database (hf_models.json) generated by 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 and 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 and 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 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 estimates memory and throughput for specific model configurations, helping operators plan resource allocation. The 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 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 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 draws bordered tables, model detail panes, and confirmation pop-ups, while tui_events.rs handles keyboard navigation and resize events.

HTTP API and MCP Server

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 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:

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:

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:

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.

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, models.rs, and analysis.rs, exposing a safe public API through 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 and hwprofile.rs, while fit analysis centralizes in analysis.rs and fit.rs.
• The workspace supports benchmarking (bench.rs), quality testing (quality.rs), and Kubernetes integration (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 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, 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. You can add it as a dependency in your 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}