# kbz-8/pulse architecture

> Architecture diagram of the GitHub repository kbz-8/pulse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kbz-8/pulse
- Repository: https://github.com/kbz-8/pulse

## Overview

##### Main Components
- Pulse Core API Layer: This is the central module (found in Sources, Includes, and the common Pulse files) that exposes functions like PulseLoadBackend, PulseCreateDevice, PulseCreateComputePipeline, etc.
- Backend Layer(s): Under Sources/Backends, there are separated directories for each graphics API (e.g., Vulkan, D3D11, OpenGL, OpenGL ES, Software, Metal, WebGPU). Each backend implements the low-level routines targeted for the specific graphics API.
- Examples & Tests: The Examples folder showcases sample client applications and the Tests directory offers unit tests that verify correctness across different components.
- Build & CI/CD Infrastructure: The .github/workflows and xmake related directories/scripts show how the project is built and tested across different platforms.
- Auxiliary Scripts: Scripts (like the GenerateOpenGLDefs.py) are used for generating binding definitions or other helper functionality.

##### Relationships and Interactions
- Client applications (as demonstrated in the README sample and Examples folder) interact with the Pulse Core API. They begin by loading a specific backend (via PulseLoadBackend) and then create a device using that backend.
- The Pulse Core then delegates calls to the appropriate backend implementation based on selection. Each backend module (Vulkan, D3D11, etc.) encapsulates the hardware or API-specific details.
- Compute pipelines, buffers, command lists, and synchronization objects (fences) are created through interface calls and then mapped to the backend implementations.
- Unit tests and CI/CD pipelines ensure cross-platform support and verify that different backends conform to expected behaviors.

##### Architectural Patterns & Design Principles
- Modularity and Backend Abstraction: The code is organized into separate backend implementations which the core API calls. This decouples the client interface from the underlying hardware specifics.
- Platform Agnosticism: Through abstraction, the same API can be used for Vulkan, WebGPU, DirectX (D3D11), OpenGL/EGL, etc.
- Build Automation & Continuous Integration: The wide range of workflow files (several .yml files under .github/workflows) indicates automated, cross-platform builds and tests.
- Extensibility: With separate directories for various backends and an examples directory, the design promotes ease of integration with new APIs in the future.

##### Final Guidance for the Principal Software Engineer
- Use directional connectors to detail data/command flows (e.g., “Device Creation”, “Command Submission”, “Computations Dispatch”).
- Ancillary pipelines such as build configurations, automated testing, and example integrations, which are significant given the multi-platform and multi-backend nature of PulseGPU.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client Layer"
        A("Client/Example Applications"):::client
    end

    subgraph "Core API Layer"
        B("Pulse Core API Layer"):::core
        BA("Backend Abstraction Interface"):::core
    end

    subgraph "Backend Implementations"
        V("Vulkan Backend"):::backend
        D("D3D11 Backend"):::backend
        O("OpenGL Backend"):::backend
        S("Software Backend"):::backend
        M("Metal Backend"):::backend
        W("WebGPU Backend"):::backend
    end

    subgraph "Testing & Build"
        UT("Unit Tests"):::test
        C("Build & CI/CD Infrastructure"):::build
        AXS("Auxiliary Scripts"):::aux
    end

    A -->|"calls"| B
    B -->|"delegates"| BA
    BA -->|"uses"| V
    BA -->|"uses"| D
    BA -->|"uses"| O
    BA -->|"uses"| S
    BA -->|"uses"| M
    BA -->|"uses"| W
    UT -->|"verifies"| B
    UT -->|"verifies"| BA
    C -->|"builds"| B
    C -->|"builds"| BA
    AXS -->|"assists"| O

    %% Click events for Pulse Core API Layer files
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseBackend.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseBuffer.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseCommandList.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseComputePass.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseComputePipeline.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseDevice.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseFence.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseImage.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Sources/PulseInternal.c"
    click B "https://github.com/kbz-8/pulse/blob/master/Includes/Pulse.h"
    click B "https://github.com/kbz-8/pulse/blob/master/Includes/PulseProfile.h"

    %% Click events for Backend Implementations
    click V "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/Vulkan"
    click D "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/D3D11"
    click O "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/OpenGL"
    click S "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/Software"
    click M "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/Metal"
    click W "https://github.com/kbz-8/pulse/tree/master/Sources/Backends/WebGPU"

    %% Click event for Example Applications
    click A "https://github.com/kbz-8/pulse/tree/master/Examples"

    %% Click event for Unit Tests
    click UT "https://github.com/kbz-8/pulse/tree/master/Tests"

    %% Click events for Build & CI/CD Infrastructure
    click C "https://github.com/kbz-8/pulse/tree/master/.github/workflows"
    click C "https://github.com/kbz-8/pulse/blob/master/xmake.lua"
    click C "https://github.com/kbz-8/pulse/tree/master/Xmake"

    %% Click event for Auxiliary Scripts
    click AXS "https://github.com/kbz-8/pulse/blob/master/Scripts/GenerateOpenGLDefs.py"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#fcf,stroke:#333,stroke-width:2px;
    classDef test fill:#cfc,stroke:#333,stroke-width:2px;
    classDef build fill:#ffc,stroke:#333,stroke-width:2px;
    classDef aux fill:#cff,stroke:#333,stroke-width:2px;
```
