# aydin-aghaliyev/mandel_on_gpu architecture

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

- Interactive diagram: https://gitdiagram.com/aydin-aghaliyev/mandel_on_gpu
- Repository: https://github.com/aydin-aghaliyev/mandel_on_gpu

## Overview

##### Project type & purpose (from README + tree)
This is a **native macOS command-line C++ program** that generates a **Mandelbrot set image** using a **Metal compute shader** for performance, then likely **writes the result as a BMP**.

Key signals:
- `main.cpp` → C++ CLI entrypoint / orchestration.
- `shader.metal` → GPU compute kernel (Metal Shading Language).
- `bmp.c`, `bmp.h` → CPU-side bitmap encoding/writing (BMP output).
- `metal-cpp/` → Apple-provided C++ headers/wrappers for Metal/Foundation/QuartzCore (vendored dependency).

##### CLI/User → Host Application
- Inputs: width/height, maxIterations, complex plane bounds, output path

##### Host Application → Metal Runtime
- “Create MTLDevice / MTLCommandQueue”
- “Create MTLBuffer/MTLTexture for output”
- “Create MTLComputePipelineState from metallib/function”

##### Metal Runtime → GPU Compute Kernel
- “Dispatch threadgroups / threads (per pixel)”

##### GPU Compute Kernel → GPU Output Resource
- Writes: RGBA bytes or float values → buffer/texture

##### Host Application ← GPU Output Resource
- “Synchronize / blit / shared memory / readback”
- Output: CPU-accessible pixel array

##### Host Application → BMP Encoder
- Input: pixel array + dimensions
- Output: BMP byte stream

##### BMP Encoder → Filesystem
- Writes: `output.bmp`

##### Build-time dependency flow (often forgotten, but key here)
- `shader.metal` → (metal compiler) → `*.metallib` → packaged next to binary or embedded
- `main.cpp` + `bmp.c` → (clang/clang++) → executable
- Executable → links against **Metal/Foundation** (system frameworks)

##### Architectural patterns/design principles to highlight
- **Heterogeneous compute**: CPU orchestrates; GPU performs data-parallel kernel.
- **Batch/offline rendering** (headless): no UI loop, just compute → encode → exit.
- **Pipeline separation**:
- “Compute pipeline” (Metal)
- “Serialization pipeline” (BMP)
- **Resource lifetime & synchronization**:
- GPU command buffer completion → CPU readback gate (important correctness detail)

##### “Don’t overthink it” decomposition checklist (maximize components)
Use this checklist to ensure you didn’t collapse important details:

Runtime:
- [ ] CLI/input parameters
- [ ] Host orchestration (`main.cpp`)
- [ ] Metal-cpp wrapper layer (`metal-cpp/`)
- [ ] Metal runtime (framework)
- [ ] Compute pipeline state (kernel binding)
- [ ] GPU resources (buffer/texture)
- [ ] Synchronization point (command buffer completion / fence)
- [ ] CPU readback buffer
- [ ] BMP encoder (`bmp.c`)
- [ ] Output file on filesystem

Build:
- [ ] Makefile
- [ ] Shader compilation step (`shader.metal` → metallib)
- [ ] C/C++ compilation and link step
- [ ] Runtime artifact location of metallib (embedded vs file next to binary) *(mark as “TBD: verify in Makefile/main.cpp” if not obvious)*

##### Sequence: One Render Invocation (Init → Dispatch → Readback → Encode → Write)
(+ optional) 4. **Build Pipeline: Makefile → metallib + executable**

That combination will be detailed, accurate to this project’s structure, and readable at principal-engineer depth.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% Diagram 1: Runtime Context
    %% =======================
    subgraph "Runtime Context: Mandelbrot Generator (Metal Compute)"
        direction TB

        User["User / CLI Invocation"]:::external
        Args["CLI Parameters\n(width,height,maxIterations,bounds,outputPath)"]:::artifact
        HostBin["Native macOS CLI Executable\n(Host Orchestration)"]:::cpu

        subgraph "Apple Runtime (System)"
            direction TB
            MetalFW["Metal.framework\n(MTLDevice/Queue/Commands)"]:::external
            FoundationFW["Foundation.framework\n(ObjC runtime helpers)"]:::external
            QuartzCoreFW["QuartzCore.framework\n(optional / headless may not need)"]:::external
        end

        GPU["GPU"]:::gpu
        FS["Filesystem"]:::external
        OutBMP[("output.bmp")]:::artifact

        User -->|"supplies"| Args
        Args -->|"configures"| HostBin

        HostBin -->|"uses"| MetalFW
        HostBin -->|"uses"| FoundationFW
        HostBin -.->|"optional"| QuartzCoreFW

        MetalFW -->|"dispatches_compute"| GPU

        HostBin -->|"writes"| FS
        FS -->|"stores"| OutBMP
    end

    %% =======================
    %% Diagram 2: Component Diagram (repo-to-runtime mapping)
    %% =======================
    subgraph "Component Diagram: main.cpp + shader.metal + bmp.c/.h + metal-cpp + Apple Frameworks"
        direction TB

        subgraph "Host Application (CPU / C++ Layer)"
            direction TB
            Main["main.cpp\nCLI parse + Metal setup + dispatch + readback"]:::cpu
            CPUReadback["CPU Pixel Buffer\n(RGBA bytes, width*height*4)"]:::artifact
        end

        subgraph "Metal C++ Bindings (vendored)"
            direction TB
            MetalCPP["metal-cpp/\nC++ wrappers for Metal/Foundation/QuartzCore"]:::vendor
            MetalHdrs["metal-cpp/Metal/\nMTLDevice/Queue/Buffer/Texture/Library..."]:::vendor
            FoundationHdrs["metal-cpp/Foundation/\nNSObject/NSString helpers"]:::vendor
            QuartzCoreHdrs["metal-cpp/QuartzCore/\n(optional layer support)"]:::vendor
            MetalCPP -->|"includes"| MetalHdrs
            MetalCPP -->|"includes"| FoundationHdrs
            MetalCPP -.->|"optional"| QuartzCoreHdrs
        end

        subgraph "GPU Compute"
            direction TB
            Metallib[("Mandelbrot.metallib\n(runtime artifact)")]:::artifact
            Kernel["shader.metal\nMandelbrot compute kernel"]:::gpu
            Pipeline["MTLComputePipelineState\n(MandelbrotKernel)"]:::external
            GPUOut["Output GPU Resource\n(MTLBuffer or MTLTexture)"]:::artifact

            Metallib -->|"contains_function"| Kernel
            Kernel -->|"writes_pixel[x,y]=rgba"| GPUOut
        end

        subgraph "Image Encoding / IO"
            direction TB
            BMPH["bmp.h\nBMP interface"]:::io
            BMPC["bmp.c\nBMP encode + write"]:::io
            BMPFile[("output.bmp")]:::artifact
            BMPH -->|"declares"| BMPC
            BMPC -->|"emits"| BMPFile
        end

        subgraph "Apple System Frameworks (Runtime APIs)"
            direction TB
            MetalRT["Metal.framework\nMTLDevice/CommandQueue/CommandBuffer/Encoder"]:::external
            FoundationRT["Foundation.framework"]:::external
            QuartzCoreRT["QuartzCore.framework (optional)"]:::external
        end

        Main -->|"uses_wrappers"| MetalCPP
        MetalCPP -->|"calls_into"| MetalRT
        MetalCPP -->|"requires"| FoundationRT
        MetalCPP -.->|"optional"| QuartzCoreRT

        Main -->|"loads_metallib (TBD:from_disk_or_embedded)"| Metallib
        Main -->|"creates_pipeline_from_library"| Pipeline
        Pipeline -->|"encodes_dispatch"| MetalRT

        Main -->|"allocates_output_resource"| GPUOut
        MetalRT -->|"dispatch_threads(per_pixel)"| Kernel

        Main -->|"wait_for_completion\n(command_buffer_completion_gate)"| MetalRT
        Main <-->|"readback/sync (shared_or_blit)"| GPUOut
        Main -->|"hands_off_pixels"| CPUReadback
        CPUReadback -->|"pixels+dimensions"| BMPC
    end

    %% =======================
    %% Diagram 3: Sequence (single render run)
    %% =======================
    subgraph "Sequence: One Render Invocation (Init → Dispatch → Readback → Encode → Write)"
        direction TB

        SUser["CLI/User"]:::external
        SHost["Host (main.cpp)"]:::cpu
        SMetal["Metal Runtime\n(MTLDevice/Queue/Commands)"]:::external
        SGPU["GPU Kernel\n(shader.metal)"]:::gpu
        SBMP["BMP Writer\n(bmp.c)"]:::io
        SFS["Filesystem"]:::external

        SUser -->|"run(width,height,iters,bounds,out)"| SHost
        SHost -->|"create_device+queue"| SMetal
        SHost -->|"load_metallib + create_pipeline"| SMetal
        SHost -->|"allocate_output_buffer_or_texture"| SMetal
        SHost -->|"encode_compute_dispatch(w*h threads)"| SMetal
        SMetal -->|"dispatch_threadgroups"| SGPU
        SGPU -->|"write_output_resource(rgba)"| SMetal
        SHost -->|"commit_command_buffer"| SMetal
        SHost -->|"wait_until_completed (sync_point)"| SMetal
        SHost <-->|"readback(width*height*4 bytes)"| SMetal
        SHost -->|"encode_BMP(pixels,dims)"| SBMP
        SBMP -->|"write(output.bmp)"| SFS
    end

    %% =======================
    %% Diagram 4: Build Pipeline (compile-time)
    %% =======================
    subgraph "Build Pipeline: Makefile → metallib + executable"
        direction TB

        Make["Makefile"]:::build
        Readme["README.md\nUsage / CLI contract"]:::doc
        SrcMain["main.cpp"]:::cpu
        SrcBMPC["bmp.c"]:::io
        SrcBMPH["bmp.h"]:::io
        SrcShader["shader.metal"]:::gpu

        MetalTool["metal\n(shader compiler)"]:::build
        MetallibTool["metallib\n(link metallib)"]:::build
        Clang["clang/clang++\ncompile + link"]:::build

        ArtExe[("mandelbrot (executable)")]:::artifact
        ArtLib[("Mandelbrot.metallib")]:::artifact

        Make -->|"drives"| MetalTool
        MetalTool -->|"produces_air"| MetallibTool
        MetallibTool -->|"outputs"| ArtLib

        Make -->|"drives"| Clang
        Clang -->|"compiles"| SrcMain
        Clang -->|"compiles"| SrcBMPC
        Clang -->|"includes"| SrcBMPH
        Clang -->|"links_with"| ArtLib
        Clang -->|"links_frameworks\nMetal/Foundation (QuartzCore optional)"| ArtExe

        Readme -.->|"documents"| Make
        Readme -.->|"documents"| ArtExe
    end

    %% =======================
    %% Click Events (from component_mapping)
    %% =======================
    click Main "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/main.cpp"
    click SHost "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/main.cpp"
    click SrcMain "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/main.cpp"
    click Kernel "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/shader.metal"
    click SGPU "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/shader.metal"
    click SrcShader "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/shader.metal"
    click BMPC "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/bmp.c"
    click SBMP "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/bmp.c"
    click SrcBMPC "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/bmp.c"
    click BMPH "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/bmp.h"
    click SrcBMPH "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/bmp.h"
    click MetalCPP "https://github.com/aydin-aghaliyev/mandel_on_gpu/tree/main/metal-cpp/"
    click MetalHdrs "https://github.com/aydin-aghaliyev/mandel_on_gpu/tree/main/metal-cpp/Metal/"
    click FoundationHdrs "https://github.com/aydin-aghaliyev/mandel_on_gpu/tree/main/metal-cpp/Foundation/"
    click QuartzCoreHdrs "https://github.com/aydin-aghaliyev/mandel_on_gpu/tree/main/metal-cpp/QuartzCore/"
    click Make "https://github.com/aydin-aghaliyev/mandel_on_gpu/tree/main/Makefile"
    click Readme "https://github.com/aydin-aghaliyev/mandel_on_gpu/blob/main/README.md"

    %% =======================
    %% Styles
    %% =======================
    classDef cpu fill:#1f77b4,stroke:#0b3a66,color:#ffffff,stroke-width:1px
    classDef gpu fill:#2ca02c,stroke:#145214,color:#ffffff,stroke-width:1px
    classDef io fill:#9467bd,stroke:#4b2e6f,color:#ffffff,stroke-width:1px
    classDef vendor fill:#17becf,stroke:#0b5f66,color:#ffffff,stroke-width:1px
    classDef external fill:#6b7280,stroke:#111827,color:#ffffff,stroke-width:1px
    classDef build fill:#f59e0b,stroke:#7a4b00,color:#111827,stroke-width:1px
    classDef artifact fill:#fb923c,stroke:#7c2d12,color:#111827,stroke-width:1px
    classDef doc fill:#fcd34d,stroke:#7a4b00,color:#111827,stroke-width:1px
```
