# sawfwair/mere-run architecture

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

- Interactive diagram: https://gitdiagram.com/sawfwair/mere-run
- Repository: https://github.com/sawfwair/mere-run

## Overview

#### Purpose and entry points
mere.run is a Swift local-first multimodal inference runtime for Apple Silicon and headless Linux. Its public entry point is the `mere.run` CLI, built from `Sources/MereRunCLI/MereRunCLI.swift`; command registration and modality dispatch live in `Sources/MereRunCLI/Commands/`. An optional macOS SwiftUI Studio is a second client over the same CLI/model-store/run concepts, rooted at `Sources/MereRunApp/MereRunApp.swift` and `Sources/MereRunApp/MereRunController.swift`.

#### Command orchestration and durable runs
CLI commands translate user requests into model resolution, preflight, inference, artifact writing, and structured output. Shared CLI support includes progress, admission, plans, and runtime pools: `Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift`, `Sources/MereRunCLI/Support/StructuredRunOutput.swift`, and `Sources/MereRunCLI/Support/RuntimeModelPool.swift`. The boundary is deliberately command-facing: modality commands own user contracts while `MereRunCore` owns model-specific execution.

#### Model lifecycle and storage
Managed model IDs resolve through catalogs, manifests, component pins, local storage, and validation before inference. Central ownership is in `Sources/MereRunCore/ManagedModelCatalog.swift`, `Sources/MereRunCore/ModelStorageManager.swift`, and `Sources/MereRunCore/MereRunModelManifest.swift`. Models are pulled from Hugging Face-backed snapshot caches and materialized into the local model store; storage locking and content sharing protect concurrent pull/remove/GC operations. Adapters follow a parallel managed catalog path (`Sources/MereRunCore/ManagedAdapterCatalog.swift`).

#### Native inference families
`Sources/MereRunCore` contains the primary MLX-backed implementations for text, image, video, music, sound, vision, 3D, and training. Each family generally encapsulates resource resolution, weight loading, preprocessing, model layers, generation/sampling, and artifact export. Representative execution roots are `Sources/MereRunCore/Gemma4/Gemma4Generator.swift`, `Sources/MereRunCore/ZImageTurbo/ZImageTurboGenerator.swift`, and `Sources/MereRunCore/Wan2/Wan2Generation.swift`. Shared decode and quantization layers—`Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift` and `Sources/MereRunCore/Quantization/QuantizationIO.swift`—cross-cut text and other autoregressive paths.

#### Audio and media boundary
Audio is split from general model code into codecs/DSP, STT, and TTS modules: `Sources/AudioCodecs/PCMStreamConverter.swift`, `Sources/AudioSTT/Parakeet/ParakeetASRLiveSession.swift`, and `Sources/AudioTTS/Qwen3TTS/Qwen3TTSTalker.swift`. `Sources/AudioCore/ASRBackendRouting.swift` selects speech-recognition backends. Media ingestion/export is abstracted behind `Sources/MediaIO/MediaIO.swift`, with Apple-native and FFmpeg implementations (`Sources/MediaIO/AppleMediaVideoIO.swift`, `Sources/MediaIO/FFmpegMediaIO.swift`); FFmpeg/ffprobe are required external executables on relevant paths.

#### Serving, workflows, and remote execution
The CLI can host an OpenAI-compatible local API through `Sources/MereRunCLI/Commands/APIServeCommand.swift`, with preflight and sidecar model-pool support in `Sources/MereRunCLI/Support/APIServePreflight.swift` and `Sources/MereRunCLI/Support/APISidecarModelPool.swift`. Portable workflow graphs are typed, preflighted, bundled, and run locally or via configured remote executors through `Sources/MereRunCLI/Support/WorkflowGraph.swift`, `Sources/MereRunCLI/Support/WorkflowRunner.swift`, and `Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift`. Relay/node services and plugins are external repositories, not hosted inference infrastructure here.

#### Runtime and platform dependencies
The principal runtime is Swift 6 with MLX/Metal on Apple Silicon; Linux is headless CLI-oriented, with CUDA-supported release lanes. Native bridges include ONNX/CoreML (`Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c`, `Sources/MereRunCore/ONNX/ONNXMLXInitializerLoader.swift`) and a llama shim (`Sources/llama/shim.h`) used by code/API paths. macOS-specific UI, media, Quick Look, and deep-link integration remain isolated in `Sources/MereRunApp/`.

Main entry points: [`Sources/MereRunCore`](https://github.com/sawfwair/mere-run/tree/main/Sources/MereRunCore) (MereRunCore), [`Sources/MereRunCore/ManagedModelCatalog.swift`](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ManagedModelCatalog.swift) (Managed model catalog), [`Sources/MereRunCore/Gemma4/Gemma4Generator.swift`](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/Gemma4/Gemma4Generator.swift) (Generation families), [`Sources/MereRunCore/ModelStorageManager.swift`](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ModelStorageManager.swift) (Local model store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_cli["mere.run CLI<br/>Swift executable<br/>[MereRunCLI.swift]"]
  node_studio["macOS Studio<br/>SwiftUI client<br/>[MereRunApp.swift]"]
  node_studio_controller["Studio controller<br/>app coordination"]
end

subgraph group_orchestration["CLI orchestration"]
  node_commands["Modality commands<br/>command dispatch"]
  node_run_support["Run plans &amp; output<br/>CLI support"]
  node_runtime_pool["Runtime model pool<br/>runtime pooling"]
  node_api_server["OpenAI-compatible API<br/>local server"]
  node_workflows["Workflow runner<br/>workflow execution"]
  node_remote_executors["Remote executors<br/>remote execution"]
end

subgraph group_models["Model lifecycle"]
  node_model_catalog["Managed model catalog<br/>model resolution"]
  node_adapter_catalog["Managed adapter catalog<br/>adapter resolution"]
  node_model_store[("Local model store<br/>storage manager")]
  node_manifest["Model manifests<br/>model metadata"]
  node_snapshot_cache[("Hugging Face snapshots<br/>external model source")]
end

subgraph group_inference["Inference runtime"]
  node_core_runtime["MereRunCore<br/>MLX inference core"]
  node_generation_families["Generation families<br/>MLX model implementations"]
  node_decode_quantization["Decode &amp; quantization<br/>shared inference layer"]
  node_native_bridges["Native ML bridges<br/>native interop"]
  node_platform_runtime{{"MLX/Metal or CUDA<br/>platform runtime"}}
end

subgraph group_media["Audio &amp; media"]
  node_audio_runtime["Audio STT/TTS<br/>audio inference"]
  node_media_io["Media I/O<br/>media boundary<br/>[MediaIO.swift]"]
  node_ffmpeg{{"FFmpeg / ffprobe<br/>external executable"}}
end

node_cli -->|"registers"| node_commands
node_studio -->|"coordinates through"| node_studio_controller
node_studio_controller -.->|"shares run concepts"| node_commands
node_commands -->|"builds plans and output"| node_run_support
node_commands -->|"uses"| node_runtime_pool
node_commands -->|"resolves models"| node_model_catalog
node_commands -->|"executes"| node_core_runtime
node_commands -->|"hosts"| node_api_server
node_commands -->|"runs"| node_workflows
node_workflows -.->|"dispatches remotely"| node_remote_executors
node_model_catalog -->|"reads"| node_manifest
node_model_catalog -->|"materializes into"| node_model_store
node_adapter_catalog -->|"manages in"| node_model_store
node_model_store -.->|"pulls snapshots from"| node_snapshot_cache
node_runtime_pool -->|"reuses loaded models"| node_core_runtime
node_core_runtime -->|"contains"| node_generation_families
node_generation_families -->|"uses"| node_decode_quantization
node_core_runtime -->|"routes audio inference"| node_audio_runtime
node_core_runtime -->|"ingests and exports media"| node_media_io
node_generation_families -->|"uses"| node_native_bridges
node_core_runtime -->|"runs on"| node_platform_runtime
node_media_io -.->|"invokes when needed"| node_ffmpeg

click node_cli "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/MereRunCLI.swift"
click node_studio "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunApp/MereRunApp.swift"
click node_studio_controller "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunApp/MereRunController.swift"
click node_run_support "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift"
click node_runtime_pool "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/RuntimeModelPool.swift"
click node_api_server "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Commands/APIServeCommand.swift"
click node_workflows "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/WorkflowRunner.swift"
click node_remote_executors "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift"
click node_model_catalog "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ManagedModelCatalog.swift"
click node_adapter_catalog "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ManagedAdapterCatalog.swift"
click node_model_store "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ModelStorageManager.swift"
click node_manifest "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/MereRunModelManifest.swift"
click node_core_runtime "https://github.com/sawfwair/mere-run/tree/main/Sources/MereRunCore"
click node_generation_families "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/Gemma4/Gemma4Generator.swift"
click node_decode_quantization "https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift"
click node_audio_runtime "https://github.com/sawfwair/mere-run/blob/main/Sources/AudioCore/ASRBackendRouting.swift"
click node_media_io "https://github.com/sawfwair/mere-run/blob/main/Sources/MediaIO/MediaIO.swift"
click node_native_bridges "https://github.com/sawfwair/mere-run/blob/main/Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c"

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_cli,node_studio,node_studio_controller toneBlue
class node_commands,node_run_support,node_runtime_pool,node_api_server,node_workflows,node_remote_executors toneAmber
class node_model_catalog,node_adapter_catalog,node_model_store,node_manifest,node_snapshot_cache toneMint
class node_core_runtime,node_generation_families,node_decode_quantization,node_native_bridges,node_platform_runtime toneRose
class node_audio_runtime,node_media_io,node_ffmpeg toneIndigo
```

## Components

### Clients

- [mere.run CLI](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/MereRunCLI.swift): Swift executable · Primary local-first runtime entry point. · `Sources/MereRunCLI/MereRunCLI.swift`
- [macOS Studio](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunApp/MereRunApp.swift): SwiftUI client · Optional graphical client over shared run and model concepts. · `Sources/MereRunApp/MereRunApp.swift`
- [Studio controller](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunApp/MereRunController.swift): app coordination · `Sources/MereRunApp/MereRunController.swift`

### CLI orchestration

- **Modality commands**: command dispatch · Own user-facing modality contracts and dispatch.
- [Run plans & output](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift): CLI support · Builds durable plans and structured results. · `Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift`
- [Runtime model pool](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/RuntimeModelPool.swift): runtime pooling · Shares loaded runtime models across runs. · `Sources/MereRunCLI/Support/RuntimeModelPool.swift`
- [OpenAI-compatible API](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Commands/APIServeCommand.swift): local server · CLI-hosted serving endpoint with preflight and sidecar pooling. · `Sources/MereRunCLI/Commands/APIServeCommand.swift`
- [Workflow runner](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/WorkflowRunner.swift): workflow execution · Runs typed, preflighted workflows locally or remotely. · `Sources/MereRunCLI/Support/WorkflowRunner.swift`
- [Remote executors](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift): remote execution · Configured external workflow execution targets. · `Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift`

### Model lifecycle

- [Managed model catalog](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ManagedModelCatalog.swift): model resolution · Resolves managed IDs, manifests, and component pins. · `Sources/MereRunCore/ManagedModelCatalog.swift`
- [Managed adapter catalog](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ManagedAdapterCatalog.swift): adapter resolution · Parallel managed lifecycle for adapters. · `Sources/MereRunCore/ManagedAdapterCatalog.swift`
- [Local model store](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/ModelStorageManager.swift): storage manager · Materializes, validates, locks, shares, and garbage-collects models. · `Sources/MereRunCore/ModelStorageManager.swift`
- [Model manifests](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/MereRunModelManifest.swift): model metadata · `Sources/MereRunCore/MereRunModelManifest.swift`
- **Hugging Face snapshots**: external model source · Snapshot cache backing model pulls.

### Inference runtime

- [MereRunCore](https://github.com/sawfwair/mere-run/tree/main/Sources/MereRunCore): MLX inference core · Model-specific resource resolution, loading, generation, and export. · `Sources/MereRunCore`
- [Generation families](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/Gemma4/Gemma4Generator.swift): MLX model implementations · Text, image, video, music, sound, vision, 3D, and training implementations. · `Sources/MereRunCore/Gemma4/Gemma4Generator.swift`
- [Decode & quantization](https://github.com/sawfwair/mere-run/blob/main/Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift): shared inference layer · Cross-cutting autoregressive decoding and quantization I/O. · `Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift`
- [Native ML bridges](https://github.com/sawfwair/mere-run/blob/main/Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c): native interop · ONNX/CoreML and llama bridge paths. · `Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c`
- **MLX/Metal or CUDA**: platform runtime · Apple Silicon MLX/Metal runtime with headless Linux CUDA release lanes.

### Audio & media

- [Audio STT/TTS](https://github.com/sawfwair/mere-run/blob/main/Sources/AudioCore/ASRBackendRouting.swift): audio inference · Speech backend routing, live ASR, and TTS. · `Sources/AudioCore/ASRBackendRouting.swift`
- [Media I/O](https://github.com/sawfwair/mere-run/blob/main/Sources/MediaIO/MediaIO.swift): media boundary · Apple-native and FFmpeg-based media ingestion and export. · `Sources/MediaIO/MediaIO.swift`
- **FFmpeg / ffprobe**: external executable · Required for relevant media paths.

## Connections

- mere.run CLI → Modality commands: registers
- macOS Studio → Studio controller: coordinates through
- Studio controller → Modality commands: shares run concepts
- Modality commands → Run plans & output: builds plans and output
- Modality commands → Runtime model pool: uses
- Modality commands → Managed model catalog: resolves models
- Modality commands → MereRunCore: executes
- Modality commands → OpenAI-compatible API: hosts
- Modality commands → Workflow runner: runs
- Workflow runner → Remote executors: dispatches remotely
- Managed model catalog → Model manifests: reads
- Managed model catalog → Local model store: materializes into
- Managed adapter catalog → Local model store: manages in
- Local model store → Hugging Face snapshots: pulls snapshots from
- Runtime model pool → MereRunCore: reuses loaded models
- MereRunCore → Generation families: contains
- Generation families → Decode & quantization: uses
- MereRunCore → Audio STT/TTS: routes audio inference
- MereRunCore → Media I/O: ingests and exports media
- Generation families → Native ML bridges: uses
- MereRunCore → MLX/Metal or CUDA: runs on
- Media I/O → FFmpeg / ffprobe: invokes when needed