# free-audio/clap architecture

> Architecture diagram of the GitHub repository free-audio/clap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/free-audio/clap
- Repository: https://github.com/free-audio/clap

## Overview

##### Main Components
- Core API Definitions: Represented by the “include/clap” headers (clap.h, entry.h, plugin.h, etc.). This is the heart of the specification.
- Extensions: Under “include/clap/ext” and “include/clap/ext/draft” – these define additional functionalities for state management, parameters, audio ports, GUI, logging, threading, etc.
- Plugin Factory and Adapter Components: Files under “include/clap/factory” and “Adapters” (linked from the README) indicate how plugins are instantiated and integrated.
- Example Implementation: The “src” directory (e.g., “plugin-template.c”, “main.c”) contains example usage and entry points to illustrate the API.
- Build and Configuration Infrastructure: CMakeLists.txt, CMakePresets.json, and workflow files (under “.github/workflows”) support building and CI/CD.
- Conventions & Artwork: “conventions” documents and “artwork” provide supplementary guidelines and branding resources.

##### Relationships and Interactions
- Extension Integration: Group the extensions into categories:
- Fundamental Extensions (e.g., state, params, note-ports, audio-ports, render, gui, etc.)
- Support Extensions (thread-check, thread-pool, log, etc.)
- Deeper Host Integration and Third-Party Extensions (remote-controls, preset-loading, etc.)
How these extension interfaces are “plugged into” the core API to add extra capabilities.
- Example Implementation Flow: Start from the entry point (defined in “entry.h”) to the execution of plugin operations, showing how the plugin’s lifecycle is managed.

##### Architectural Patterns and Design Principles
- Interface-based Design: Stress the design based solely on well-defined C structures with function pointers (e.g., clap_plugin_xxx and clap_host_xxx). This decouples implementation from the interface.
- Extension Mechanism: Clearly indicate that extensions are add-ons, and illustrate how versioning and unique identifiers (as shown in the conventions documents) ensure backward compatibility.
- Modularity: Separate core API from extensions, and tag experimental/draft features accordingly.
- ABI Stability: Emphasize that the design is built to maintain ARI stability even when new versions or features are added.

##### Relevant Technologies, Frameworks, and Libraries
- C/CMake: Represent the build system components with CMakeLists and configuration files.
- GitHub Workflows: Mention CI/CD pipelines for automated builds and tests.
- Community Adapters & Bindings: Note that several bindings exist for languages like Rust, Delphi, Zig, and Ada (as referenced in the README).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core API Subgraph
    subgraph "Core API"
        Core1["clap.h"]:::core
        Core2["entry.h"]:::core
        Core3["plugin.h"]:::core
    end

    %% Extensions Subgraphs
    subgraph "Stable Extensions"
        ES["Stable Extensions (include/clap/ext)"]:::ext
    end

    subgraph "Draft Extensions"
        ED["Draft Extensions (include/clap/ext/draft)"]:::ext
    end

    %% Plugin Factory Subgraph
    subgraph "Plugin Factory"
        PF["Plugin Factory (include/clap/factory)"]:::factory
    end

    %% Example Implementation Subgraph
    subgraph "Example Implementation"
        PT["Plugin Template (src/plugin-template.c)"]:::example
        MC["Main (src/main.c)"]:::example
        MCC["Main (src/main.cc)"]:::example
    end

    %% Host and Plugin Interaction
    Host["CLAP Host"]:::host
    Plugin["CLAP Plugin"]:::host

    %% Build and CI Infrastructure Subgraph
    subgraph "Build & CI Infrastructure"
        CMake["CMake (CMakeLists.txt)"]:::build
        Presets["CMake Presets (CMakePresets.json)"]:::build
        Workflows["CI Workflows (.github/workflows/cmake.yml)"]:::build
    end

    %% Conventions & Artwork Subgraph
    subgraph "Conventions & Artwork"
        Conv["Conventions (conventions)"]:::docs
        Art["Artwork (artwork)"]:::docs
    end

    %% Connections between components

    %% Core API integrates with Extensions
    Core2 -->|"integrates"| ES
    Core2 -->|"integrates"| ED

    %% Core API used by Plugin Factory and Example Implementation
    Core2 -->|"defines entry"| PF
    Core2 -->|"defines entry"| PT

    %% Plugin Factory instantiates the plugin example
    PF -->|"instantiates"| PT

    %% Example Implementation forms the CLAP Plugin
    PT -->|"implements"| Plugin

    %% Host and Plugin Communication
    Host -->|"queriesExtensions"| Plugin
    Plugin -->|"usesFacilities"| Host

    %% Build infrastructure supports the implementation
    CMake -->|"builds"| PT
    Presets -->|"configures"| PF
    Workflows -->|"CI/CD for"| PT

    %% Conventions & Artwork guide the Core API design
    Conv -->|"guides"| Core1
    Art -->|"branding"| Core1

    %% Class Definitions for styling
    classDef core fill:#aee,stroke:#333,stroke-width:2px;
    classDef ext fill:#afa,stroke:#333,stroke-width:2px;
    classDef factory fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef example fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef build fill:#ccd,stroke:#333,stroke-width:2px;
    classDef docs fill:#cfc,stroke:#333,stroke-width:2px;
    classDef host fill:#f99,stroke:#333,stroke-width:2px;

    %% Click Events for Core API Definitions
    click Core1 "https://github.com/free-audio/clap/blob/main/include/clap/clap.h"
    click Core2 "https://github.com/free-audio/clap/blob/main/include/clap/entry.h"
    click Core3 "https://github.com/free-audio/clap/blob/main/include/clap/plugin.h"

    %% Click Events for Extensions
    click ES "https://github.com/free-audio/clap/tree/main/include/clap/ext"
    click ED "https://github.com/free-audio/clap/tree/main/include/clap/ext/draft"

    %% Click Event for Plugin Factory
    click PF "https://github.com/free-audio/clap/tree/main/include/clap/factory"

    %% Click Events for Example Implementation
    click PT "https://github.com/free-audio/clap/blob/main/src/plugin-template.c"
    click MC "https://github.com/free-audio/clap/blob/main/src/main.c"
    click MCC "https://github.com/free-audio/clap/blob/main/src/main.cc"

    %% Click Events for Build and Configuration
    click CMake "https://github.com/free-audio/clap/blob/main/CMakeLists.txt"
    click Presets "https://github.com/free-audio/clap/blob/main/CMakePresets.json"
    click Workflows "https://github.com/free-audio/clap/blob/main/.github/workflows/cmake.yml"

    %% Click Events for Conventions & Artwork
    click Conv "https://github.com/free-audio/clap/tree/main/conventions"
    click Art "https://github.com/free-audio/clap/tree/main/artwork"
```
