# eyelash/libgral architecture

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

- Interactive diagram: https://gitdiagram.com/eyelash/libgral
- Repository: https://github.com/eyelash/libgral

## Overview

##### Project Type and Purpose
- libgral is a low-level abstraction library written in C (with some Objective-C and C++ for specific platforms) that provides a unified API to work with window creation, event handling, drawing (text, images, vector graphics), clipboard access, PCM audio output, and MIDI events.
- The library is designed to work across multiple operating systems including Linux, macOS, and Windows. The README and the platform-specific source files highlight this cross-platform focus.
- The “demos” directory contains sample applications demonstrating the usage of the library in various scenarios (e.g., audio, file dialogs, cursor handling).

##### File Structure
- At the top level, you see configuration files (.editorconfig, LICENSE, CMakeLists.txt) and a README that describes the project.
- The core library files are:
- gral.h: Public header exposing the unified API.
- gral_linux.c, gral_unix.c: Implementations for Linux/Unix systems.
- gral_macos.m: The macOS-specific implementation.
- gral_windows.cpp: Windows-specific code.
- The presence of CMakeLists.txt files indicates that the project is built using CMake, which is crucial for understanding the build and integration dependencies.

##### Key Architectural Components
a. Core API Layer:
- This is represented by gral.h which defines the common interface for consumers of libgral.
b. Platform-Specific Implementations:
- macOS: gral_macos.m.
- Windows: gral_windows.cpp.
c. Demo Applications:
- Demos serve as client applications and usage examples that illustrate how the API interacts with the underlying platform-specific implementations.
d. Build System:
- CMake configuration (CMakeLists.txt at root and in demos) which orchestrates the build process and handles platform selections via conditional compilation.

##### Relationships and Interactions
- The central element is the “Unified C API” provided by gral.h.
- The CMake build system should be represented as a separate tool/component that governs the build process, selecting the correct backend based on the operating system.

##### Architectural Patterns & Design Principles
- Abstraction/Encapsulation – The design uses an abstraction layer (the public API) to hide platform-specific details.
- Platform-dependent implementation selection – Using separate source files for each OS to keep the code organized.
- Modularity – The demos being isolated in their own directory indicates testing/usage examples are decoupled from the core library code.
- Cross-platform support – Emphasize the use of conditional builds (via CMake and OS-specific source files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System component
    Build("CMake Build System"):::build

    %% Core API Layer
    API("Unified API (gral.h)"):::api

    %% Platform-Specific Implementations
    Unix("Linux/Unix Implementation (gral_linux.c / gral_unix.c)"):::backend
    Mac("macOS Implementation (gral_macos.m)"):::backend
    Win("Windows Implementation (gral_windows.cpp)"):::backend

    %% Demo Applications
    Demo("Demo Applications (demos/)"):::demo

    %% Relationships/Interactions
    Build -->|"builds"| API
    Build -->|"builds"| Unix
    Build -->|"builds"| Mac
    Build -->|"builds"| Win
    API -->|"delegates"| Unix
    API -->|"delegates"| Mac
    API -->|"delegates"| Win
    Demo -->|"calls"| API

    %% Click Events
    click API "https://github.com/eyelash/libgral/blob/main/gral.h"
    click Unix "https://github.com/eyelash/libgral/blob/main/gral_linux.c"
    click Unix "https://github.com/eyelash/libgral/blob/main/gral_unix.c"
    click Mac "https://github.com/eyelash/libgral/blob/main/gral_macos.m"
    click Win "https://github.com/eyelash/libgral/blob/main/gral_windows.cpp"
    click Demo "https://github.com/eyelash/libgral/tree/main/demos/"
    click Build "https://github.com/eyelash/libgral/blob/main/CMakeLists.txt"
    click Build "https://github.com/eyelash/libgral/blob/main/demos/CMakeLists.txt"

    %% Styles (colors)
    classDef api fill:#f9f,stroke:#333,stroke-width:2px;
    classDef backend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef demo fill:#ff9,stroke:#333,stroke-width:2px;
    classDef build fill:#9f9,stroke:#333,stroke-width:2px;
```
