# youssofal/mtplx architecture

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

- Interactive diagram: https://gitdiagram.com/youssofal/mtplx
- Repository: https://github.com/youssofal/mtplx

## Overview

MTPLX is a local Apple Silicon language-model runtime with a macOS app, CLI, and monitoring dashboard. The main workflow is choosing and preparing a model, serving it locally, and generating responses with the model’s MTP heads and speculative verification. The map also includes model-building (Forge), cache/session state, and dashboard monitoring. Several runtime relationships are documented in the README; where sampled source does not establish a connection, the edge is marked unverified rather than treated as inspected.

Main entry points: [`mtplx/cli.py`](https://github.com/youssofal/mtplx/blob/main/mtplx/cli.py) (MTPLX CLI), [`mtplx/generation.py`](https://github.com/youssofal/mtplx/blob/main/mtplx/generation.py) (Speculative Generation), [`mtplx/server/openai.py`](https://github.com/youssofal/mtplx/blob/main/mtplx/server/openai.py) (HTTP API), [`apps/MTPLXApp/Sources/MTPLXAppHost/App/MTPLXApp.swift`](https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppHost/App/MTPLXApp.swift) (Mac App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and Models"]
  node_onboarding["Setup Flow"]
  node_runtime_setup["Runtime Setup"]
  node_command_builder["Launch Builder"]
  node_catalog["Model Catalog<br/>[model_catalog.py]"]
  node_forge["Model Forge<br/>[forge.py]"]
end

subgraph group_runtime["Inference Runtime"]
  node_backend_registry["Backend Registry<br/>[registry.py]"]
  node_model_backend["Model Backends<br/>[qwen4_exp.py]"]
  node_generation["Speculative Generation<br/>[generation.py]"]
  node_profiles["Runtime Profiles<br/>[profiles.py]"]
  node_cache[("KV Cache<br/>[cache_state.py]")]
  node_session_bank[("Session Bank<br/>[session_bank.py]")]
  node_engine_session["Engine Sessions<br/>[engine_session.py]"]
end

subgraph group_serving["Serving and Integrations"]
  node_server["HTTP API<br/>[openai.py]"]
  node_responses["Responses API<br/>[responses.py]"]
  node_daemon_client["Daemon Client<br/>[daemon_client.py]"]
  node_integrations["Client Integrations<br/>[opencode.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_macapp["Mac App<br/>[MTPLXApp.swift]"]
  node_cli["MTPLX CLI<br/>[cli.py]"]
end

subgraph group_monitoring["Monitoring"]
  node_dashboard_stream["Metrics Stream"]
  node_dashboard_store["Dashboard State<br/>[store.ts]"]
  node_dashboard["Metrics Dashboard<br/>[App.tsx]"]
end

node_user(("User"))

node_user -->|"uses"| node_macapp
node_user -->|"runs"| node_cli
node_macapp -.->|"starts setup"| node_onboarding
node_onboarding -->|"prepares runtime"| node_runtime_setup
node_runtime_setup -->|"configures commands"| node_command_builder
node_command_builder -->|"launches"| node_cli
node_user -->|"selects model"| node_catalog
node_cli -.->|"resolves model"| node_catalog
node_user -->|"creates model"| node_forge
node_cli -.->|"loads backend"| node_backend_registry
node_backend_registry -.->|"dispatches to"| node_model_backend
node_model_backend -.->|"supplies model"| node_generation
node_generation -.->|"uses runtime settings"| node_profiles
node_generation -.->|"uses KV state"| node_cache
node_generation -.->|"uses session state"| node_session_bank
node_session_bank -->|"stores cache state"| node_cache
node_engine_session -.->|"tracks sessions"| node_session_bank
node_cli -->|"serves API"| node_server
node_server -.->|"offers endpoint"| node_responses
node_daemon_client -.->|"attaches to"| node_server
node_integrations -->|"calls API"| node_server
node_macapp -.->|"offers monitoring"| node_dashboard
node_dashboard -->|"starts stream"| node_dashboard_stream
node_dashboard_stream -->|"applies events"| node_dashboard_store
node_dashboard -->|"reads state"| node_dashboard_store

click node_macapp "https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppHost/App/MTPLXApp.swift"
click node_onboarding "https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/OnboardingOrchestrator.swift"
click node_runtime_setup "https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/RuntimeSetupService.swift"
click node_command_builder "https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Services/MTPLXCommandBuilder.swift"
click node_catalog "https://github.com/youssofal/mtplx/blob/main/mtplx/model_catalog.py"
click node_forge "https://github.com/youssofal/mtplx/blob/main/mtplx/commands/forge.py"
click node_cli "https://github.com/youssofal/mtplx/blob/main/mtplx/cli.py"
click node_backend_registry "https://github.com/youssofal/mtplx/blob/main/mtplx/backends/registry.py"
click node_model_backend "https://github.com/youssofal/mtplx/blob/main/mtplx/models/qwen4_exp.py"
click node_generation "https://github.com/youssofal/mtplx/blob/main/mtplx/generation.py"
click node_profiles "https://github.com/youssofal/mtplx/blob/main/mtplx/profiles.py"
click node_cache "https://github.com/youssofal/mtplx/blob/main/mtplx/cache_state.py"
click node_session_bank "https://github.com/youssofal/mtplx/blob/main/mtplx/session_bank.py"
click node_engine_session "https://github.com/youssofal/mtplx/blob/main/mtplx/engine_session.py"
click node_server "https://github.com/youssofal/mtplx/blob/main/mtplx/server/openai.py"
click node_responses "https://github.com/youssofal/mtplx/blob/main/mtplx/server/responses.py"
click node_daemon_client "https://github.com/youssofal/mtplx/blob/main/mtplx/daemon_client.py"
click node_integrations "https://github.com/youssofal/mtplx/blob/main/mtplx/opencode.py"
click node_dashboard_stream "https://github.com/youssofal/mtplx/blob/main/dashboard/src/hooks/useMetricsStream.ts"
click node_dashboard_store "https://github.com/youssofal/mtplx/blob/main/dashboard/src/state/store.ts"
click node_dashboard "https://github.com/youssofal/mtplx/blob/main/dashboard/src/App.tsx"

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_onboarding,node_runtime_setup,node_command_builder,node_catalog,node_forge,node_user toneBlue
class node_backend_registry,node_model_backend,node_generation,node_profiles,node_cache,node_session_bank,node_engine_session toneAmber
class node_server,node_responses,node_daemon_client,node_integrations toneMint
class node_macapp,node_cli toneRose
class node_dashboard_stream,node_dashboard_store,node_dashboard toneIndigo
```

## Components

### Setup and Models

- [Setup Flow](https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/OnboardingOrchestrator.swift): `apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/OnboardingOrchestrator.swift`
- [Runtime Setup](https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/RuntimeSetupService.swift): `apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/RuntimeSetupService.swift`
- [Launch Builder](https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppCore/Services/MTPLXCommandBuilder.swift): `apps/MTPLXApp/Sources/MTPLXAppCore/Services/MTPLXCommandBuilder.swift`
- [Model Catalog](https://github.com/youssofal/mtplx/blob/main/mtplx/model_catalog.py): `mtplx/model_catalog.py`
- [Model Forge](https://github.com/youssofal/mtplx/blob/main/mtplx/commands/forge.py): `mtplx/commands/forge.py`

### Inference Runtime

- [Backend Registry](https://github.com/youssofal/mtplx/blob/main/mtplx/backends/registry.py): `mtplx/backends/registry.py`
- [Model Backends](https://github.com/youssofal/mtplx/blob/main/mtplx/models/qwen4_exp.py): `mtplx/models/qwen4_exp.py`
- [Speculative Generation](https://github.com/youssofal/mtplx/blob/main/mtplx/generation.py): `mtplx/generation.py`
- [Runtime Profiles](https://github.com/youssofal/mtplx/blob/main/mtplx/profiles.py): `mtplx/profiles.py`
- [KV Cache](https://github.com/youssofal/mtplx/blob/main/mtplx/cache_state.py): `mtplx/cache_state.py`
- [Session Bank](https://github.com/youssofal/mtplx/blob/main/mtplx/session_bank.py): `mtplx/session_bank.py`
- [Engine Sessions](https://github.com/youssofal/mtplx/blob/main/mtplx/engine_session.py): `mtplx/engine_session.py`

### Serving and Integrations

- [HTTP API](https://github.com/youssofal/mtplx/blob/main/mtplx/server/openai.py): `mtplx/server/openai.py`
- [Responses API](https://github.com/youssofal/mtplx/blob/main/mtplx/server/responses.py): `mtplx/server/responses.py`
- [Daemon Client](https://github.com/youssofal/mtplx/blob/main/mtplx/daemon_client.py): `mtplx/daemon_client.py`
- [Client Integrations](https://github.com/youssofal/mtplx/blob/main/mtplx/opencode.py): `mtplx/opencode.py`

### User Interfaces

- [Mac App](https://github.com/youssofal/mtplx/blob/main/apps/MTPLXApp/Sources/MTPLXAppHost/App/MTPLXApp.swift): `apps/MTPLXApp/Sources/MTPLXAppHost/App/MTPLXApp.swift`
- [MTPLX CLI](https://github.com/youssofal/mtplx/blob/main/mtplx/cli.py): `mtplx/cli.py`

### Monitoring

- [Metrics Stream](https://github.com/youssofal/mtplx/blob/main/dashboard/src/hooks/useMetricsStream.ts): `dashboard/src/hooks/useMetricsStream.ts`
- [Dashboard State](https://github.com/youssofal/mtplx/blob/main/dashboard/src/state/store.ts): `dashboard/src/state/store.ts`
- [Metrics Dashboard](https://github.com/youssofal/mtplx/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`

### Other components

- **User**

## Connections

- User → Mac App: uses (evidence: `README.md`)
- User → MTPLX CLI: runs (evidence: `README.md`)
- Mac App → Setup Flow: starts setup
- Setup Flow → Runtime Setup: prepares runtime (evidence: `apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/RuntimeSetupService.swift`)
- Runtime Setup → Launch Builder: configures commands (evidence: `apps/MTPLXApp/Sources/MTPLXAppCore/Onboarding/RuntimeSetupService.swift`)
- Launch Builder → MTPLX CLI: launches (evidence: `apps/MTPLXApp/Sources/MTPLXAppCore/Services/MTPLXCommandBuilder.swift`)
- User → Model Catalog: selects model (evidence: `README.md`)
- MTPLX CLI → Model Catalog: resolves model
- User → Model Forge: creates model (evidence: `README.md`)
- MTPLX CLI → Backend Registry: loads backend
- Backend Registry → Model Backends: dispatches to
- Model Backends → Speculative Generation: supplies model
- Speculative Generation → Runtime Profiles: uses runtime settings
- Speculative Generation → KV Cache: uses KV state
- Speculative Generation → Session Bank: uses session state
- Session Bank → KV Cache: stores cache state (evidence: `mtplx/session_bank.py`)
- Engine Sessions → Session Bank: tracks sessions (evidence: `mtplx/engine_session.py`)
- MTPLX CLI → HTTP API: serves API (evidence: `README.md`)
- HTTP API → Responses API: offers endpoint
- Daemon Client → HTTP API: attaches to
- Client Integrations → HTTP API: calls API (evidence: `README.md`)
- Mac App → Metrics Dashboard: offers monitoring
- Metrics Dashboard → Metrics Stream: starts stream (evidence: `dashboard/src/App.tsx`)
- Metrics Stream → Dashboard State: applies events (evidence: `dashboard/src/hooks/useMetricsStream.ts`)
- Metrics Dashboard → Dashboard State: reads state (evidence: `dashboard/src/App.tsx`)
