# raullenchai/rapid-mlx architecture

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

- Interactive diagram: https://gitdiagram.com/raullenchai/rapid-mlx
- Repository: https://github.com/raullenchai/rapid-mlx

## Overview

Rapid-MLX combines an Apple-Silicon inference server with a macOS desktop client. The main workflow is a client sending OpenAI- or Anthropic-compatible requests to the server, which validates and adapts them before model inference and returns generated results. The repository also includes separate agent-runtime, computer-use, MCP, image, and video capabilities. Relationships are limited to those stated in the README or visible in the supplied source index and excerpts; several desktop-to-server and unsampled subsystem links remain unverified.

Main entry points: [`rapid_mlx/server.py`](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/server.py) (API Server), [`rapid_mlx/agent_runtime/server.py`](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/server.py) (Agent Server), [`apps/rapid-mac/Sources/Rapid/RapidApp.swift`](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/RapidApp.swift) (Rapid Desktop), [`rapid_mlx/image/engine.py`](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/image/engine.py) (Image Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Serving"]
  node_server["API Server<br/>[server.py]"]
  node_schemas["API Schemas<br/>[models.py]"]
  node_helpers["Route Helpers<br/>[helpers.py]"]
  node_errors["Error Handling"]
end

subgraph group_runtime["Inference Runtime"]
  node_engine["Batch Engine<br/>[engine_core.py]"]
  node_config["Server Config<br/>[__init__.py]"]
end

subgraph group_media["Media Generation"]
  node_image["Image Engine<br/>[engine.py]"]
  node_video["Video Engine<br/>[engine.py]"]
  node_video_pipeline["Video Pipeline"]
end

subgraph group_agents["Agent Capabilities"]
  node_agent_server["Agent Server<br/>[server.py]"]
  node_agent_runtime["Agent Runtime<br/>[runtime.py]"]
  node_agent_models["Agent Models<br/>[models.py]"]
  node_cua_server["Computer Use Server<br/>[server.py]"]
  node_cua_service["Computer Use Service<br/>[service.py]"]
  node_cua_backend["Computer Use Backend<br/>[backend.py]"]
  node_mcp_manager["MCP Manager<br/>[manager.py]"]
  node_mcp_client["MCP Client<br/>[client.py]"]
end

subgraph group_desktop["Mac Desktop"]
  node_desktop_app["Rapid Desktop<br/>[RapidApp.swift]"]
  node_chat["Chat Interface<br/>[ChatView.swift]"]
  node_chat_model["Chat View Model"]
  node_chat_stream["Chat Streaming"]
  node_dictation["Dictation"]
  node_audio["Audio Client<br/>[AudioClient.swift]"]
end

node_client(("API Client"))
node_desktop_user(("Desktop User"))

node_client -->|"sends requests"| node_server
node_server -->|"uses schemas"| node_schemas
node_server -->|"delegates"| node_helpers
node_server -->|"installs handlers"| node_errors
node_server -->|"loads config"| node_config
node_server -.->|"dispatches inference"| node_engine
node_server -.->|"offers generation"| node_image
node_image -.->|"separate media capability"| node_video
node_video -->|"runs pipeline"| node_video_pipeline
node_server -.->|"separate runtime"| node_agent_server
node_agent_server -->|"uses runtime"| node_agent_runtime
node_agent_server -->|"uses models"| node_agent_models
node_cua_server -->|"routes to"| node_cua_service
node_cua_service -->|"uses backend"| node_cua_backend
node_mcp_manager -->|"uses client"| node_mcp_client
node_desktop_user -.->|"uses"| node_desktop_app
node_desktop_app -.->|"presents chat"| node_chat
node_chat -.->|"binds view model"| node_chat_model
node_chat_model -.->|"streams replies"| node_chat_stream
node_desktop_app -.->|"offers dictation"| node_dictation
node_dictation -->|"uses audio client"| node_audio

click node_server "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/server.py"
click node_schemas "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/api/models.py"
click node_helpers "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/service/helpers.py"
click node_errors "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/middleware/exception_handlers.py"
click node_engine "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/engine_core.py"
click node_config "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/config/__init__.py"
click node_image "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/image/engine.py"
click node_video "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/video/engine.py"
click node_video_pipeline "https://github.com/raullenchai/rapid-mlx/blob/main/videox_fun_mlx/pipeline/pipeline_cogvideox_fun_inpaint.py"
click node_agent_server "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/server.py"
click node_agent_runtime "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/runtime.py"
click node_agent_models "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/models.py"
click node_cua_server "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/cua/server.py"
click node_cua_service "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/cua/service.py"
click node_cua_backend "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/computer_use/backend.py"
click node_mcp_manager "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/mcp/manager.py"
click node_mcp_client "https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/mcp/client.py"
click node_desktop_app "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/RapidApp.swift"
click node_chat "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/UI/ChatView.swift"
click node_chat_model "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Chat/ChatViewModel.swift"
click node_chat_stream "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Chat/ChatStreamClient.swift"
click node_dictation "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Dictation/DictationController.swift"
click node_audio "https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Audio/AudioClient.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_server,node_schemas,node_helpers,node_errors,node_client,node_desktop_user toneBlue
class node_engine,node_config toneAmber
class node_image,node_video,node_video_pipeline toneMint
class node_agent_server,node_agent_runtime,node_agent_models,node_cua_server,node_cua_service,node_cua_backend,node_mcp_manager,node_mcp_client toneRose
class node_desktop_app,node_chat,node_chat_model,node_chat_stream,node_dictation,node_audio toneIndigo
```

## Components

### API Serving

- [API Server](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/server.py): `rapid_mlx/server.py`
- [API Schemas](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/api/models.py): `rapid_mlx/api/models.py`
- [Route Helpers](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/service/helpers.py): `rapid_mlx/service/helpers.py`
- [Error Handling](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/middleware/exception_handlers.py): `rapid_mlx/middleware/exception_handlers.py`

### Inference Runtime

- [Batch Engine](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/engine_core.py): `rapid_mlx/engine_core.py`
- [Server Config](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/config/__init__.py): `rapid_mlx/config/__init__.py`

### Media Generation

- [Image Engine](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/image/engine.py): `rapid_mlx/image/engine.py`
- [Video Engine](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/video/engine.py): `rapid_mlx/video/engine.py`
- [Video Pipeline](https://github.com/raullenchai/rapid-mlx/blob/main/videox_fun_mlx/pipeline/pipeline_cogvideox_fun_inpaint.py): `videox_fun_mlx/pipeline/pipeline_cogvideox_fun_inpaint.py`

### Agent Capabilities

- [Agent Server](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/server.py): `rapid_mlx/agent_runtime/server.py`
- [Agent Runtime](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/runtime.py): `rapid_mlx/agent_runtime/runtime.py`
- [Agent Models](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/agent_runtime/models.py): `rapid_mlx/agent_runtime/models.py`
- [Computer Use Server](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/cua/server.py): `rapid_mlx/cua/server.py`
- [Computer Use Service](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/cua/service.py): `rapid_mlx/cua/service.py`
- [Computer Use Backend](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/computer_use/backend.py): `rapid_mlx/computer_use/backend.py`
- [MCP Manager](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/mcp/manager.py): `rapid_mlx/mcp/manager.py`
- [MCP Client](https://github.com/raullenchai/rapid-mlx/blob/main/rapid_mlx/mcp/client.py): `rapid_mlx/mcp/client.py`

### Mac Desktop

- [Rapid Desktop](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/RapidApp.swift): `apps/rapid-mac/Sources/Rapid/RapidApp.swift`
- [Chat Interface](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/UI/ChatView.swift): `apps/rapid-mac/Sources/Rapid/UI/ChatView.swift`
- [Chat View Model](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Chat/ChatViewModel.swift): `apps/rapid-mac/Sources/Rapid/Chat/ChatViewModel.swift`
- [Chat Streaming](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Chat/ChatStreamClient.swift): `apps/rapid-mac/Sources/Rapid/Chat/ChatStreamClient.swift`
- [Dictation](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Dictation/DictationController.swift): `apps/rapid-mac/Sources/Rapid/Dictation/DictationController.swift`
- [Audio Client](https://github.com/raullenchai/rapid-mlx/blob/main/apps/rapid-mac/Sources/Rapid/Audio/AudioClient.swift): `apps/rapid-mac/Sources/Rapid/Audio/AudioClient.swift`

### Other components

- **API Client**
- **Desktop User**

## Connections

- API Client → API Server: sends requests (evidence: `README.md`)
- API Server → API Schemas: uses schemas (evidence: `rapid_mlx/server.py`)
- API Server → Route Helpers: delegates (evidence: `rapid_mlx/server.py`)
- API Server → Error Handling: installs handlers (evidence: `rapid_mlx/server.py`)
- API Server → Server Config: loads config (evidence: `rapid_mlx/server.py`)
- API Server → Batch Engine: dispatches inference
- API Server → Image Engine: offers generation
- Image Engine → Video Engine: separate media capability
- Video Engine → Video Pipeline: runs pipeline (evidence: `rapid_mlx/video/engine.py`)
- API Server → Agent Server: separate runtime
- Agent Server → Agent Runtime: uses runtime (evidence: `rapid_mlx/agent_runtime/server.py`)
- Agent Server → Agent Models: uses models (evidence: `rapid_mlx/agent_runtime/server.py`)
- Computer Use Server → Computer Use Service: routes to (evidence: `rapid_mlx/cua/server.py`)
- Computer Use Service → Computer Use Backend: uses backend (evidence: `rapid_mlx/cua/service.py`)
- MCP Manager → MCP Client: uses client (evidence: `rapid_mlx/mcp/manager.py`)
- Desktop User → Rapid Desktop: uses
- Rapid Desktop → Chat Interface: presents chat
- Chat Interface → Chat View Model: binds view model
- Chat View Model → Chat Streaming: streams replies
- Rapid Desktop → Dictation: offers dictation
- Dictation → Audio Client: uses audio client (evidence: `apps/rapid-mac/Sources/Rapid/Dictation/DictationController.swift`)
