# ml-explore/mlx-swift architecture

> Architecture diagram of the GitHub repository ml-explore/mlx-swift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ml-explore/mlx-swift
- Repository: https://github.com/ml-explore/mlx-swift

## Overview

##### Project Type and Purpose
- MLX Swift is a language‐binding library that exposes the core MLX C++ array and computation framework to Swift.
- It is not an end‐user app but a multi‐module SDK: a C++ “backend” (Cmlx) plus Swift “frontend” layers (MLX, MLXNN, MLXOptimizers, MLXRandom), packaged for SwiftPM, Xcode, or CMake.

##### File‐Structure Analysis
- Top‐level build/config:
- CMakeLists.txt, Package.swift (SwiftPM), .circleci/config.yml (CI), .gitmodules (fmt, JSON)
- tools/ (codegen, docs, metal‐include fixes)
- Source/Cmlx: the C++ core, with submodules:
- fmt (formatting library)
- json (nlohmann JSON)
- metal-cpp (Objective-C++ wrappers for Metal)
- generated code (mlx-generated/*.cpp, .metal shaders)
- Source/MLX* Swift modules:
- MLX (core Swift API + bridging)
- MLXNN (neural network layers)
- MLXOptimizers, MLXRandom, MLXFFT, MLXFast, MLXLinalg
- Tests/ verify both C++ (CmlxTests) and Swift modules (MLXTests).

##### README Insights
- Confirms multi‐target Swift package with CMake compatibility.
- Mentions building Metal shaders only in Xcode/xcodebuild.
- Emphasizes modular libraries (MLX, MLXNN, etc.) built atop MLX C core.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Tools & Systems
    subgraph "Build Tools & Systems"
        direction TB
        Codegen["tools/ (codegen scripts)"]:::build
        CMake["CMakeLists.txt & cmake/"]:::build
        SwiftPM["Package.swift"]:::build
        Xcode["Xcode Build"]:::build
    end

    %% C++ Core
    subgraph "C++ Core (Cmlx)" 
        direction TB
        Cmlx["Cmlx"]:::cpp
        fmtLib["fmt"]:::external
        jsonLib["nlohmann_json"]:::external
        metalCpp["metal-cpp wrappers"]:::external
        genKernels["Generated C++ & Metal kernels"]:::cpp
    end

    %% Swift Modules
    subgraph "Swift Modules"
        direction TB
        MLX["MLX"]:::swift
        MLXNN["MLXNN"]:::swift
        MLXOpt["MLXOptimizers"]:::swift
        MLXRand["MLXRandom"]:::swift
        MLXFFT["MLXFFT"]:::swift
        MLXFast["MLXFast"]:::swift
        MLXLinalg["MLXLinalg"]:::swift
    end

    %% CI & Tests
    subgraph "CI/CD & Tests"
        direction TB
        CI[".circleci/config.yml"]:::build
        CppTests["CmlxTests"]:::test
        SwiftTests["MLXTests"]:::test
    end

    %% Build-time flows
    Codegen -->|generates| genKernels
    CMake -->|compiles| Cmlx
    SwiftPM -->|compiles| Cmlx
    Xcode -->|compiles shaders| genKernels
    CMake -->|links| fmtLib
    CMake -->|links| jsonLib
    CMake -->|links| metalCpp
    CMake -->|builds| MLX
    SwiftPM -->|builds| MLX
    SwiftPM -->|builds| MLXNN
    SwiftPM -->|builds| MLXOpt
    SwiftPM -->|builds| MLXRand
    SwiftPM -->|builds| MLXFFT
    SwiftPM -->|builds| MLXFast
    SwiftPM -->|builds| MLXLinalg

    %% Runtime flows
    MLX -->|"Swift API calls"| Cmlx
    MLXNN -->|"uses MLX API"| MLX
    MLXOpt -->|"uses MLX API"| MLX
    MLXRand -->|"uses MLX API"| MLX
    MLXFFT -->|"uses MLX API"| MLX
    MLXFast -->|"uses MLX API"| MLX
    MLXLinalg -->|"uses MLX API"| MLX
    Cmlx -->|"dispatches GPU kernels via"| metalCpp

    %% Testing & CI
    CI -->|runs| CppTests
    CI -->|runs| SwiftTests

    %% Click events
    click Cmlx "https://github.com/ml-explore/mlx-swift/tree/main/Source/Cmlx"
    click fmtLib "https://github.com/ml-explore/mlx-swift/tree/main/Source/Cmlx/fmt"
    click jsonLib "https://github.com/ml-explore/mlx-swift/tree/main/Source/Cmlx/json"
    click metalCpp "https://github.com/ml-explore/mlx-swift/tree/main/Source/Cmlx/metal-cpp"
    click genKernels "https://github.com/ml-explore/mlx-swift/tree/main/Source/Cmlx/mlx-generated"
    click Codegen "https://github.com/ml-explore/mlx-swift/tree/main/tools/"
    click CMake "https://github.com/ml-explore/mlx-swift/blob/main/CMakeLists.txt"
    click SwiftPM "https://github.com/ml-explore/mlx-swift/blob/main/Package.swift"
    click MLX "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLX"
    click MLXNN "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXNN"
    click MLXOpt "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXOptimizers"
    click MLXRand "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXRandom"
    click MLXFFT "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXFFT"
    click MLXFast "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXFast"
    click MLXLinalg "https://github.com/ml-explore/mlx-swift/tree/main/Source/MLXLinalg"
    click CI "https://github.com/ml-explore/mlx-swift/blob/main/.circleci/config.yml"
    click CppTests "https://github.com/ml-explore/mlx-swift/blob/main/Tests/CmlxTests/CmlxTests.swift"
    click SwiftTests "https://github.com/ml-explore/mlx-swift/tree/main/Tests/MLXTests"

    %% Styles
    classDef build fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef cpp fill:#add8e6,stroke:#333,stroke-width:1px
    classDef swift fill:#98fb98,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef test fill:#ffe4e1,stroke:#333,stroke-width:1px
```
