# paglaai/paglamlx architecture

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

- Interactive diagram: https://gitdiagram.com/paglaai/paglamlx
- Repository: https://github.com/paglaai/paglamlx

## Overview

PaglaMLX is a macOS menu-bar control plane for local MLX inference, with a Python gateway providing stable OpenAI- and Anthropic-compatible APIs. The main workflow is to configure Python and model settings, start model servers, then send client requests through the gateway to local models or configured cloud providers. The app also provides client integrations, activity and system monitoring, benchmarking, and optional remote access. Unsampled capabilities and links are included only where the README documents them.

Main entry points: [`Sources/RoutingGateway.swift`](https://github.com/paglaai/paglamlx/blob/main/Sources/RoutingGateway.swift) (API gateway), [`Sources/ModelOrchestrator.swift`](https://github.com/paglaai/paglamlx/blob/main/Sources/ModelOrchestrator.swift) (Model lifecycle), [`Sources/ContentView.swift`](https://github.com/paglaai/paglamlx/blob/main/Sources/ContentView.swift) (Main workspace), [`Sources/SettingsManager.swift`](https://github.com/paglaai/paglamlx/blob/main/Sources/SettingsManager.swift) (App settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and configuration"]
  node_app_ui["Menu-bar UI<br/>[MenuBarView.swift]"]
  node_main_view["Main workspace<br/>[ContentView.swift]"]
  node_settings_ui["Settings UI<br/>[SettingsView.swift]"]
  node_settings["App settings"]
  node_preflight["Environment checks<br/>[Preflight.swift]"]
  node_integrations["Client integrations"]
  node_keychain[("Keychain credentials")]
end

subgraph group_runtime["Inference runtime"]
  node_orchestrator["Model lifecycle"]
  node_model_server["MLX model server"]
end

subgraph group_routing["Routing and providers"]
  node_gateway["API gateway"]
  node_anthropic["Anthropic translation"]
  node_cloud["Cloud providers"]
end

subgraph group_operations["Operations and access"]
  node_activity["Activity tracking"]
  node_event_watcher["Event log watcher"]
  node_system_monitor["System monitor"]
  node_benchmark["Inference benchmark"]
  node_remote["Remote access"]
  node_tunnel["Cloudflare tunnel"]
  node_health["Provider health"]
end

node_developer(("API client"))

node_developer -->|"sends requests"| node_gateway
node_app_ui -->|"manages models"| node_orchestrator
node_main_view -->|"controls lifecycle"| node_orchestrator
node_settings_ui -->|"edits settings"| node_settings
node_settings_ui -->|"applies client configs"| node_integrations
node_settings_ui -->|"checks providers"| node_health
node_settings -.->|"stores credentials"| node_keychain
node_preflight -->|"reads configuration"| node_settings
node_orchestrator -->|"checks environment"| node_preflight
node_orchestrator -->|"reads configuration"| node_settings
node_orchestrator -->|"starts gateway"| node_gateway
node_orchestrator -->|"launches processes"| node_model_server
node_gateway -->|"forwards inference"| node_model_server
node_gateway -->|"dispatches cloud requests"| node_cloud
node_gateway -->|"translates messages"| node_anthropic
node_gateway -->|"reads configuration"| node_settings
node_event_watcher -->|"records events"| node_activity
node_main_view -->|"shows activity"| node_activity
node_main_view -->|"runs benchmark"| node_benchmark
node_benchmark -->|"sends inference request"| node_gateway
node_main_view -->|"shows system status"| node_system_monitor
node_main_view -->|"shows remote address"| node_remote
node_remote -->|"checks tunnel URL"| node_tunnel
node_tunnel -->|"tunnels gateway traffic"| node_gateway

click node_app_ui "https://github.com/paglaai/paglamlx/blob/main/Sources/MenuBarView.swift"
click node_main_view "https://github.com/paglaai/paglamlx/blob/main/Sources/ContentView.swift"
click node_settings_ui "https://github.com/paglaai/paglamlx/blob/main/Sources/SettingsView.swift"
click node_settings "https://github.com/paglaai/paglamlx/blob/main/Sources/SettingsManager.swift"
click node_preflight "https://github.com/paglaai/paglamlx/blob/main/Sources/Preflight.swift"
click node_integrations "https://github.com/paglaai/paglamlx/blob/main/Sources/IntegrationManager.swift"
click node_orchestrator "https://github.com/paglaai/paglamlx/blob/main/Sources/ModelOrchestrator.swift"
click node_gateway "https://github.com/paglaai/paglamlx/blob/main/Sources/RoutingGateway.swift"
click node_anthropic "https://github.com/paglaai/paglamlx/blob/main/Sources/AnthropicProxy.swift"
click node_keychain "https://github.com/paglaai/paglamlx/blob/main/Sources/PaglaMLXCore/KeychainStore.swift"
click node_activity "https://github.com/paglaai/paglamlx/blob/main/Sources/ActivityTracker.swift"
click node_event_watcher "https://github.com/paglaai/paglamlx/blob/main/Sources/EventLogWatcher.swift"
click node_system_monitor "https://github.com/paglaai/paglamlx/blob/main/Sources/SystemMonitorManager.swift"
click node_benchmark "https://github.com/paglaai/paglamlx/blob/main/Sources/BenchmarkManager.swift"
click node_remote "https://github.com/paglaai/paglamlx/blob/main/Sources/RemoteAccessManager.swift"
click node_tunnel "https://github.com/paglaai/paglamlx/blob/main/Sources/TunnelManager.swift"
click node_health "https://github.com/paglaai/paglamlx/blob/main/Sources/CloudProviderHealth.swift"

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_app_ui,node_main_view,node_settings_ui,node_settings,node_preflight,node_integrations,node_keychain,node_developer toneBlue
class node_orchestrator,node_model_server toneAmber
class node_gateway,node_anthropic,node_cloud toneMint
class node_activity,node_event_watcher,node_system_monitor,node_benchmark,node_remote,node_tunnel,node_health toneRose
```

## Components

### App and configuration

- [Menu-bar UI](https://github.com/paglaai/paglamlx/blob/main/Sources/MenuBarView.swift): `Sources/MenuBarView.swift`
- [Main workspace](https://github.com/paglaai/paglamlx/blob/main/Sources/ContentView.swift): `Sources/ContentView.swift`
- [Settings UI](https://github.com/paglaai/paglamlx/blob/main/Sources/SettingsView.swift): `Sources/SettingsView.swift`
- [App settings](https://github.com/paglaai/paglamlx/blob/main/Sources/SettingsManager.swift): `Sources/SettingsManager.swift`
- [Environment checks](https://github.com/paglaai/paglamlx/blob/main/Sources/Preflight.swift): `Sources/Preflight.swift`
- [Client integrations](https://github.com/paglaai/paglamlx/blob/main/Sources/IntegrationManager.swift): `Sources/IntegrationManager.swift`
- [Keychain credentials](https://github.com/paglaai/paglamlx/blob/main/Sources/PaglaMLXCore/KeychainStore.swift): `Sources/PaglaMLXCore/KeychainStore.swift`

### Inference runtime

- [Model lifecycle](https://github.com/paglaai/paglamlx/blob/main/Sources/ModelOrchestrator.swift): `Sources/ModelOrchestrator.swift`
- **MLX model server**

### Routing and providers

- [API gateway](https://github.com/paglaai/paglamlx/blob/main/Sources/RoutingGateway.swift): `Sources/RoutingGateway.swift`
- [Anthropic translation](https://github.com/paglaai/paglamlx/blob/main/Sources/AnthropicProxy.swift): `Sources/AnthropicProxy.swift`
- **Cloud providers**

### Operations and access

- [Activity tracking](https://github.com/paglaai/paglamlx/blob/main/Sources/ActivityTracker.swift): `Sources/ActivityTracker.swift`
- [Event log watcher](https://github.com/paglaai/paglamlx/blob/main/Sources/EventLogWatcher.swift): `Sources/EventLogWatcher.swift`
- [System monitor](https://github.com/paglaai/paglamlx/blob/main/Sources/SystemMonitorManager.swift): `Sources/SystemMonitorManager.swift`
- [Inference benchmark](https://github.com/paglaai/paglamlx/blob/main/Sources/BenchmarkManager.swift): `Sources/BenchmarkManager.swift`
- [Remote access](https://github.com/paglaai/paglamlx/blob/main/Sources/RemoteAccessManager.swift): `Sources/RemoteAccessManager.swift`
- [Cloudflare tunnel](https://github.com/paglaai/paglamlx/blob/main/Sources/TunnelManager.swift): `Sources/TunnelManager.swift`
- [Provider health](https://github.com/paglaai/paglamlx/blob/main/Sources/CloudProviderHealth.swift): `Sources/CloudProviderHealth.swift`

### Other components

- **API client**

## Connections

- API client → API gateway: sends requests (evidence: `README.md`)
- Menu-bar UI → Model lifecycle: manages models (evidence: `README.md`)
- Main workspace → Model lifecycle: controls lifecycle (evidence: `Sources/ContentView.swift`)
- Settings UI → App settings: edits settings (evidence: `Sources/SettingsView.swift`)
- Settings UI → Client integrations: applies client configs (evidence: `Sources/SettingsView.swift`)
- Settings UI → Provider health: checks providers (evidence: `Sources/SettingsView.swift`)
- App settings → Keychain credentials: stores credentials (evidence: `README.md`)
- Environment checks → App settings: reads configuration (evidence: `Sources/Preflight.swift`)
- Model lifecycle → Environment checks: checks environment (evidence: `Sources/ModelOrchestrator.swift`)
- Model lifecycle → App settings: reads configuration (evidence: `Sources/ModelOrchestrator.swift`)
- Model lifecycle → API gateway: starts gateway (evidence: `Sources/ModelOrchestrator.swift`)
- Model lifecycle → MLX model server: launches processes (evidence: `README.md`)
- API gateway → MLX model server: forwards inference (evidence: `README.md`)
- API gateway → Cloud providers: dispatches cloud requests (evidence: `README.md`)
- API gateway → Anthropic translation: translates messages (evidence: `Sources/RoutingGateway.swift`)
- API gateway → App settings: reads configuration (evidence: `Sources/RoutingGateway.swift`)
- Event log watcher → Activity tracking: records events (evidence: `Sources/EventLogWatcher.swift`)
- Main workspace → Activity tracking: shows activity (evidence: `Sources/ContentView.swift`)
- Main workspace → Inference benchmark: runs benchmark (evidence: `Sources/ContentView.swift`)
- Inference benchmark → API gateway: sends inference request (evidence: `Sources/BenchmarkManager.swift`)
- Main workspace → System monitor: shows system status (evidence: `Sources/ContentView.swift`)
- Main workspace → Remote access: shows remote address (evidence: `Sources/ContentView.swift`)
- Remote access → Cloudflare tunnel: checks tunnel URL (evidence: `Sources/RemoteAccessManager.swift`)
- Cloudflare tunnel → API gateway: tunnels gateway traffic (evidence: `Sources/TunnelManager.swift`)
