# recp/cglm architecture

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

- Interactive diagram: https://gitdiagram.com/recp/cglm
- Repository: https://github.com/recp/cglm

## Overview

##### Project Type and Purpose
- This is a low-level math library optimized for 2D/3D operations, matrix algebra, vector math, affine transformations, quaternions, and more. It is designed to be used in graphics programming with APIs like OpenGL, Vulkan, or Metal.
- Its goal is to provide allocation-free, SIMD-optimized math routines with multiple API options (header-only, linked, and struct-based).

##### Analyzing the File Structure
- Top-level directories:
- “include” – Contains the public header files that declare the API functions and data structures (with separate directories for the “call”, “struct”, and SIMD-specific interfaces).
- “src” – Contains the implementation of the library functions. This includes various mathematical operations like matrix operations, vector functions, affine transforms, and orthogonal projections.
- “docs” – Contains documentation sources (Sphinx/reStructuredText) which are used to generate the online documentation.
- “test” – Contains test files, test harnesses and CMake build scripts that ensure the correctness and stability of the library.
- Build and configuration files (e.g., CMakeLists.txt, configure.ac, meson.build, Makefile.am, Package.swift) show that multiple build systems and platforms are supported.
- There are also CI/CD configuration files under “.github/workflows”, “.travis.yml”, and others, indicating continuous integration processes.

##### Key Components
a. Core Library Components:
- Public API Layer: Represented by the “include/cglm” folder. This includes the entire API (divided into the header-only API, the core “cglm.h”, and other specialized headers in “call”, “struct”, etc.).
- Implementation Layer: Represented by the files in “src”, covering the actual functions for vectors, matrices, affine transformations, quaternions, etc.
- SIMD/Optimized Subsystem: Within both the “include” and “src” directories, there are SIMD-specific headers and implementations for platforms (SSE, AVX, Neon, WASM, x86). This can be shown as a special module that augments core functions with architecture-specific optimizations.

b. Build/Configuration and Toolchain:
- Build Systems: The project supports multiple build systems (CMake, Meson, Autotools, and Swift’s Package Manager). Represent these toolchains as external modules interacting with the core library.
- Documentation Generation: A component for “Docs & Doxygen/Sphinx” shows the linkage between the source (docs folder and README) and the published documentation.

c. Test Framework:
- Testing Suite: Located in the “test” directory where unit tests are organized to validate different components of the library.

##### Relationships and Interactions
- The Public API (headers) is the interface used directly by consumers of the library. It interacts with the underlying implementations in the “src” directory.
- The SIMD/optimized submodule augments both the API and the implementation, indicating optional paths or configuration flags (like alignment/disabling alignment).
- Build systems are used to compile the source or package the header-only version. They interact with both the implementation and test suites.
- CI systems automatically trigger builds and tests which validate that changes in the code (both in “src” and “include”) remain correct.
- Documentation tools take annotations from the header/source files to create user-friendly documentation.

##### Final Advice
- That cglm is used in different modes (header-only vs. linked), so representing these usage paths adds clarity.
- You clearly show the separation of concerns: the mathematical computation layer is decoupled from the build/test/infrastructure parts.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Library Components
    subgraph "Core Library"
        UM["Usage Modes (header-only, linked, struct-based)"]:::usage
        API["Public API – Header-Only Library"]:::api
        Impl["Core Mathematical Implementations"]:::impl
        SIMD["SIMD/Optimization Module"]:::simd
    end

    %% External Infrastructure Components
    subgraph "External Infrastructure"
        subgraph "Build Systems/Toolchain"
            CMake["CMakeLists.txt"]:::tools
            Meson["meson.build"]:::tools
            Auto["configure.ac"]:::tools
            Makefile["Makefile.am"]:::tools
            Swift["Package.swift"]:::tools
        end
        CI["CI/CD Infrastructure"]:::ci
        Docs["Documentation Generation"]:::docs
        Test["Testing Suite"]:::test
    end

    %% Relationships within Core Library
    UM -->|"uses"| API
    API -->|"calls"| Impl
    API -->|"augments"| SIMD
    Impl -->|"optimized_by"| SIMD

    %% Build Systems interactions with Core Library
    CMake -->|"builds"| API
    CMake -->|"builds"| Impl
    Meson -->|"builds"| API
    Meson -->|"builds"| Impl
    Auto -->|"builds"| API
    Auto -->|"builds"| Impl
    Makefile -->|"builds"| API
    Makefile -->|"builds"| Impl
    Swift -->|"builds"| API
    Swift -->|"builds"| Impl

    %% CI/CD interactions
    CI -->|"triggers"| CMake
    CI -->|"runs"| Test

    %% Documentation interactions
    Docs -->|"documents"| API
    Docs -->|"documents"| Impl

    %% Styling
    classDef usage fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef api fill:#e6f7ff,stroke:#005f99,stroke-width:2px;
    classDef impl fill:#e6ffe6,stroke:#008000,stroke-width:2px;
    classDef simd fill:#fff0b3,stroke:#b38f00,stroke-width:2px;
    classDef tools fill:#f0e6ff,stroke:#5e0080,stroke-width:2px;
    classDef ci fill:#e6f0ff,stroke:#004d99,stroke-width:2px;
    classDef docs fill:#f0fff0,stroke:#006600,stroke-width:2px;
    classDef test fill:#fff0f5,stroke:#99004d,stroke-width:2px;

    %% Click Events
    click API "https://github.com/recp/cglm/tree/master/include/cglm"
    click Impl "https://github.com/recp/cglm/tree/master/src"
    click SIMD "https://github.com/recp/cglm/tree/master/include/cglm/simd"
    click CMake "https://github.com/recp/cglm/blob/master/CMakeLists.txt"
    click Meson "https://github.com/recp/cglm/blob/master/meson.build"
    click Auto "https://github.com/recp/cglm/blob/master/configure.ac"
    click Makefile "https://github.com/recp/cglm/blob/master/Makefile.am"
    click Swift "https://github.com/recp/cglm/blob/master/Package.swift"
    click CI "https://github.com/recp/cglm/tree/master/.github/workflows"
    click Docs "https://github.com/recp/cglm/tree/master/docs"
    click Test "https://github.com/recp/cglm/tree/master/test"
```
