# jimdawdy-hub/local-llm-launcher-gui architecture

> Architecture diagram of the GitHub repository jimdawdy-hub/local-llm-launcher-gui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jimdawdy-hub/local-llm-launcher-gui
- Repository: https://github.com/jimdawdy-hub/local-llm-launcher-gui

## Overview

1. **What this repo is**
   - A **local-first desktop-style web app** for managing LLM models on the user’s own machine.
   - The architecture is split into a **Python backend** that does all system/model/launch work and a **React frontend** that presents the control panel UI.
   - The app is intended to run entirely on `127.0.0.1` and serve its own built frontend assets.

2. **Top-level runtime shape**
   - The Python package in `src/local_llm_launcher` is the core runtime.
   - The frontend in `frontend/` is a separate Vite/React app whose production build is embedded into `src/local_llm_launcher/static/`.
   - The backend appears to be the long-lived orchestrator: it discovers hardware, inspects installed engines, manages downloads, launches model servers, and tracks running state.

3. **Backend entrypoints and serving boundary**
   - `__main__.py` and `app.py` are the startup path for the package.
   - `api.py` is the HTTP boundary between frontend and backend.
   - `static/` contains the compiled frontend bundle, so the Python process likely serves both the API and the UI from one local process.
   - This makes the backend the single source of truth for state; the frontend is mostly a client rendering backend-derived status.

4. **Frontend structure**
   - The frontend is organized by views: `Dashboard`, `Models`, `Launch`, `Servers`, and `Settings`.
   - `api.js` centralizes browser-to-backend calls.
   - `App.jsx` and `main.jsx` wire the SPA shell, while `components.jsx` and `theme.css` provide shared UI building blocks and styling.
   - The UI is operational rather than generic: each page maps to a backend subsystem like discovery, model selection, launch configuration, or active server control.

5. **Hardware and environment discovery**
   - `hardware.py` and `discovery.py` detect the local machine’s capabilities and installed tooling.
   - This includes GPU/VRAM or RAM availability, plus whether supported engines are present.
   - The results feed directly into the “Fit / Tight / Won’t fit” recommendations and the dashboard health summary.
   - This is a critical boundary: the app is not guessing from static model metadata alone; it evaluates against the user’s current machine state.

6. **Model catalog and fit/advice logic**
   - `catalog.py` holds model/engine metadata and likely the flag/preset definitions used to configure launches.
   - `advisor.py` performs the core decision logic: it compares a model’s memory needs with available hardware and emits the green/yellow/red verdicts plus plain-English reasoning.
   - `data/flags_vllm.json`, `data/flags_llamacpp.json`, and `data/failures.json` are static knowledge bases used to keep those recommendations consistent.
   - `failures.py` likely maps launch errors into human-readable diagnoses using those failure definitions.

7. **Downloads and model storage**
   - `downloads.py` handles fetching models, most likely from Hugging Face.
   - The Models page is therefore both a catalog browser and a local asset manager: it can inspect what is already present and trigger new downloads.
   - The download subsystem sits between the frontend and the filesystem/network, with the backend keeping track of local model locations and availability.

8. **Launch engine subsystem**
   - The `engines/` package abstracts the different ways to run a model server.
   - `base.py` defines the common engine contract; `_args.py` likely normalizes command-line construction.
   - `llamacpp.py`, `vllm_native.py`, and `vllm_docker.py` are concrete launch paths for the supported runtimes.
   - The key architectural point is that the rest of the app does not launch models directly; it asks a selected engine implementation to build and run the correct server process.

9. **Server lifecycle and running-state tracking**
   - `registry.py` appears to track active servers, their ports, model assignments, and status.
   - The Servers page in the UI is likely backed by this registry so it can show logs, addresses, and current process state.
   - This registry is the coordination point between launch requests, process lifetime, and UI status display.

10. **Configuration and user-specific environment**
   - `config.py` manages user settings such as Hugging Face tokens, extra model directories, and executable paths like `llama-server`.
   - These settings matter because they affect model access, discovery success, and which engines can be launched.
   - The Settings page is therefore not just preferences; it configures the backend’s ability to find and run local resources.

11. **Open WebUI integration**
   - `openwebui.py` provides a secondary integration path: launching Open WebUI and connecting it to the running model server.
   - This is a separate external app, but it is treated as part of the local workflow and surfaced from the dashboard.
   - Architecturally, it is an optional companion process started by the backend rather than a core subsystem.

12. **Data flow across the system**
   - Frontend actions call the backend API.
   - The backend consults discovery/hardware state, model catalog data, and config.
   - Advisor logic produces launch suitability and recommendations.
   - If the user proceeds, an engine implementation starts a local model server.
   - The registry records the live server, and the UI reads that state back for logs, connection info, and troubleshooting.

13. **Testing and reliability boundaries**
   - The `tests/` suite covers advisor logic, API behavior, catalog/discovery, hardware, engines, Open WebUI integration, and registry behavior.
   - That test structure mirrors the core architecture: separate verification for system inspection, planning, launching, and runtime management.
   - For an architecture diagram, this repo should be drawn as a **local orchestrator + UI + engine adapters** system, not as a monolithic chat app.

14. **Implementation stack that materially affects architecture**
   - Backend: **Python 3.10+** package layout under `src/`.
   - Frontend: **React + Vite**, bundled into static assets served by the Python app.
   - Model serving backends: **vLLM** and **llama.cpp**, with an optional **Docker-based vLLM** path.
   - External dependency surfaces: local GPUs/CPU/RAM, Hugging Face model sources, and optionally Open WebUI.

Main entry points: [`src/local_llm_launcher/api.py`](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/api.py) (HTTP API), [`src/local_llm_launcher/engines/base.py`](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/base.py) (Engine base), [`src/local_llm_launcher/advisor.py`](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/advisor.py) (Advisor), [`src/local_llm_launcher/registry.py`](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/registry.py) (Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react spa<br/>[App.jsx]"]
  node_frontend_api["API client<br/>browser client<br/>[api.js]"]
  node_frontend_views["Views<br/>screens"]
  node_frontend_components["UI kit<br/>shared ui<br/>[components.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_main["Startup<br/>entrypoint<br/>[__main__.py]"]
  node_backend_app["App host<br/>server bootstrap<br/>[app.py]"]
  node_backend_api["HTTP API<br/>local api<br/>[api.py]"]
  node_hardware_discovery["Discovery<br/>system probe<br/>[discovery.py]"]
  node_hardware_state["Hardware<br/>resource model<br/>[hardware.py]"]
  node_model_catalog["Catalog<br/>model metadata<br/>[catalog.py]"]
  node_model_advisor["Advisor<br/>fit logic<br/>[advisor.py]"]
  node_download_mgr["Downloads<br/>model fetcher<br/>[downloads.py]"]
  node_config_mgr["Config<br/>settings store<br/>[config.py]"]
  node_server_registry["Registry<br/>runtime state<br/>[registry.py]"]
  node_openwebui_integration["Open WebUI<br/>optional integration<br/>[openwebui.py]"]
end

subgraph group_engines["Launch engines"]
  node_engine_base["Engine base<br/>engine contract<br/>[base.py]"]
  node_engine_args["Arg builder<br/>launch helper<br/>[_args.py]"]
  node_engine_llamacpp["llama.cpp<br/>engine adapter<br/>[llamacpp.py]"]
  node_engine_vllm_native["vLLM native<br/>engine adapter<br/>[vllm_native.py]"]
  node_engine_vllm_docker["vLLM Docker<br/>engine adapter<br/>[vllm_docker.py]"]
end

subgraph group_data["Data"]
  node_flags_failures["Rules data<br/>static knowledge"]
end

node_frontend_app -->|"renders"| node_frontend_views
node_frontend_app -->|"uses"| node_frontend_components
node_frontend_views -->|"calls"| node_frontend_api
node_backend_main -->|"starts"| node_backend_app
node_backend_app -->|"serves"| node_backend_api
node_backend_app -->|"serves static"| node_frontend_app
node_backend_api -->|"queries"| node_hardware_discovery
node_hardware_discovery -->|"builds"| node_hardware_state
node_backend_api -->|"reads"| node_model_catalog
node_backend_api -->|"evaluates"| node_model_advisor
node_model_advisor -->|"compares against"| node_hardware_state
node_model_advisor -->|"uses metadata"| node_model_catalog
node_backend_api -->|"downloads"| node_download_mgr
node_backend_api -->|"loads"| node_config_mgr
node_backend_api -->|"tracks"| node_server_registry
node_backend_api -->|"launches via"| node_engine_base
node_engine_base -->|"builds"| node_engine_args
node_engine_base -->|"implements"| node_engine_llamacpp
node_engine_base -->|"implements"| node_engine_vllm_native
node_engine_base -->|"implements"| node_engine_vllm_docker
node_engine_llamacpp -->|"registers"| node_server_registry
node_engine_vllm_native -->|"registers"| node_server_registry
node_engine_vllm_docker -->|"registers"| node_server_registry
node_backend_api -->|"optionally starts"| node_openwebui_integration
node_model_advisor -->|"uses rules"| node_flags_failures
node_engine_base -->|"uses rules"| node_flags_failures

click node_frontend_app "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/App.jsx"
click node_frontend_api "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/api.js"
click node_frontend_views "https://github.com/jimdawdy-hub/local-llm-launcher-gui/tree/master/frontend/src/views"
click node_frontend_components "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/components.jsx"
click node_backend_main "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/__main__.py"
click node_backend_app "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/app.py"
click node_backend_api "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/api.py"
click node_hardware_discovery "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/discovery.py"
click node_hardware_state "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/hardware.py"
click node_model_catalog "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/catalog.py"
click node_model_advisor "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/advisor.py"
click node_download_mgr "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/downloads.py"
click node_config_mgr "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/config.py"
click node_server_registry "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/registry.py"
click node_openwebui_integration "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/openwebui.py"
click node_engine_base "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/base.py"
click node_engine_args "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/_args.py"
click node_engine_llamacpp "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/llamacpp.py"
click node_engine_vllm_native "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/vllm_native.py"
click node_engine_vllm_docker "https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/vllm_docker.py"
click node_flags_failures "https://github.com/jimdawdy-hub/local-llm-launcher-gui/tree/master/src/local_llm_launcher/data"

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_frontend_app,node_frontend_api,node_frontend_views,node_frontend_components toneBlue
class node_backend_main,node_backend_app,node_backend_api,node_hardware_discovery,node_hardware_state,node_model_catalog,node_model_advisor,node_download_mgr,node_config_mgr,node_server_registry,node_openwebui_integration toneAmber
class node_engine_base,node_engine_args,node_engine_llamacpp,node_engine_vllm_native,node_engine_vllm_docker toneMint
class node_flags_failures toneRose
```

## Components

### Frontend

React/Vite SPA served as static assets

- [App shell](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/App.jsx): react spa · Top-level SPA wiring and view layout · `frontend/src/App.jsx`
- [API client](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/api.js): browser client · Centralized frontend calls into the backend API · `frontend/src/api.js`
- [Views](https://github.com/jimdawdy-hub/local-llm-launcher-gui/tree/master/frontend/src/views): screens · Dashboard, Models, Launch, Servers, and Settings screens · `frontend/src/views`
- [UI kit](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/frontend/src/components.jsx): shared ui · Reusable components and theme styling · `frontend/src/components.jsx`

### Backend

Python orchestrator and local API

- [Startup](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/__main__.py): entrypoint · Package entry path and app bootstrap · `src/local_llm_launcher/__main__.py`
- [App host](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/app.py): server bootstrap · Initializes and serves the local application · `src/local_llm_launcher/app.py`
- [HTTP API](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/api.py): local api · Boundary between the UI and backend state/actions · `src/local_llm_launcher/api.py`
- [Discovery](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/discovery.py): system probe · Detects hardware and installed tooling · `src/local_llm_launcher/discovery.py`
- [Hardware](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/hardware.py): resource model · Represents local CPU, RAM, and GPU capability · `src/local_llm_launcher/hardware.py`
- [Catalog](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/catalog.py): model metadata · Model, engine, and preset metadata · `src/local_llm_launcher/catalog.py`
- [Advisor](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/advisor.py): fit logic · Computes fit verdicts and plain-English recommendations · `src/local_llm_launcher/advisor.py`
- [Downloads](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/downloads.py): model fetcher · Fetches and tracks local model assets · `src/local_llm_launcher/downloads.py`
- [Config](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/config.py): settings store · User settings, paths, tokens, and environment overrides · `src/local_llm_launcher/config.py`
- [Registry](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/registry.py): runtime state · Tracks active servers, ports, and process state · `src/local_llm_launcher/registry.py`
- [Open WebUI](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/openwebui.py): optional integration · Launches and connects an external companion UI · `src/local_llm_launcher/openwebui.py`

### Launch engines

Adapters for running model servers

- [Engine base](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/base.py): engine contract · Common engine interface and launch contract · `src/local_llm_launcher/engines/base.py`
- [Arg builder](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/_args.py): launch helper · Normalizes command-line construction for engines · `src/local_llm_launcher/engines/_args.py`
- [llama.cpp](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/llamacpp.py): engine adapter · Concrete launcher for llama.cpp servers · `src/local_llm_launcher/engines/llamacpp.py`
- [vLLM native](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/vllm_native.py): engine adapter · Concrete launcher for native vLLM servers · `src/local_llm_launcher/engines/vllm_native.py`
- [vLLM Docker](https://github.com/jimdawdy-hub/local-llm-launcher-gui/blob/master/src/local_llm_launcher/engines/vllm_docker.py): engine adapter · Concrete launcher for Docker-based vLLM servers · `src/local_llm_launcher/engines/vllm_docker.py`

### Data

Static knowledge and configuration inputs

- [Rules data](https://github.com/jimdawdy-hub/local-llm-launcher-gui/tree/master/src/local_llm_launcher/data): static knowledge · Launch flags and failure diagnosis definitions · `src/local_llm_launcher/data`

## Connections

- App shell → Views: renders · Shell composes the operational views
- App shell → UI kit: uses · Shared UI primitives and theme support
- Views → API client: calls · Views fetch state and trigger backend actions through the client
- Startup → App host: starts · Entry point boots the application host
- App host → HTTP API: serves · Host exposes the local HTTP boundary
- App host → App shell: serves static · Python app serves the built frontend bundle
- HTTP API → Discovery: queries · API triggers environment and hardware inspection
- Discovery → Hardware: builds · Discovery results populate the hardware model
- HTTP API → Catalog: reads · API exposes catalog and model metadata
- HTTP API → Advisor: evaluates · API asks for fit advice and recommendations
- Advisor → Hardware: compares against · Advice uses current machine capability
- Advisor → Catalog: uses metadata · Advice uses model and engine requirements
- HTTP API → Downloads: downloads · API initiates model fetching and inventory updates
- HTTP API → Config: loads · API reads user settings and environment configuration
- HTTP API → Registry: tracks · API exposes active server state and lifecycle
- HTTP API → Engine base: launches via · API selects an engine implementation to start servers
- Engine base → Arg builder: builds · Engine contract uses normalized command construction
- Engine base → llama.cpp: implements · llama.cpp is one concrete launch path
- Engine base → vLLM native: implements · native vLLM is one concrete launch path
- Engine base → vLLM Docker: implements · Docker vLLM is one concrete launch path
- llama.cpp → Registry: registers · Running processes are recorded for UI and lifecycle control
- vLLM native → Registry: registers · Running processes are recorded for UI and lifecycle control
- vLLM Docker → Registry: registers · Running processes are recorded for UI and lifecycle control
- HTTP API → Open WebUI: optionally starts · Backend can launch the companion Open WebUI process
- Advisor → Rules data: uses rules · Static flag and failure knowledge keeps recommendations consistent
- Engine base → Rules data: uses rules · Engine launch behavior is informed by the same knowledge base