# oguztoraman/libmagicxx architecture

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

- Interactive diagram: https://gitdiagram.com/oguztoraman/libmagicxx
- Repository: https://github.com/oguztoraman/libmagicxx

## Overview

##### Project type and purpose
- Libmagicxx is a native C++ wrapper library (API-only, no UI) over the libmagic C library, exposing a `magic` class for file-type recognition.
- It is built and packaged via CMake for consumption by downstream C++ projects, and includes tests, examples, CI workflows, and generated documentation.

##### File structure
- Top-level CMakeLists.txt, CMakePresets.json, `cmake/` modules: define build targets (shared/static libs), packaging and installation rules.
- `include/magicxx/`: public headers that define the C++ API.
- `sources/`: implementation of the wrapper (`magic.cpp`).
- `external/`: vendored dependencies (googletest, libgnurx, and a copy of the libmagic header).
- `tests/`: unit tests using GoogleTest.
- `examples/`: example applications demonstrating API usage.
- `documentation/html/`: Doxygen-generated API docs.
- `.github/workflows/`, `Containerfile`, `scripts/`: CI/CD pipelines, container builds, release automation, and install scripts.

##### Key insights from README
- Core functionality: provide C++23 high-level, exception-safe API for libmagic (states, flags, identify calls).
- Package variables for CMake consumers (include dirs, lib dirs, version, shared vs static).
- Multi-platform support (Linux/Windows) and packaging formats (DEB, RPM, NSIS installer).
- Examples and docs are first-class artifacts, integrated into CI.

##### Components
a. Main components
1. C++ Wrapper Module
- Public API (headers in `include/magicxx/`)
- Implementation (`sources/magic.cpp`)
2. libmagic (underlying C library)
- Dynamically or statically linked
3. Build System & Packaging
- CMake core files + custom `cmake/` modules
- Packaging config (CPack scripts: DEB, RPM, NSIS)
4. External Dependencies
- libgnurx (regex engine)
- GoogleTest (unit testing)
5. Examples & Tests
- Example executables (in `examples/`)
- Test suite (in `tests/`)
6. Documentation
- Doxygen generator → static HTML (`documentation/html/`)
7. CI/CD Pipelines
- GitHub Actions workflows (build & test on Linux/Windows, deploy docs and packages)
- Containerfile for reproducible builds

b. Relationships and interactions
- The C++ Wrapper invokes libmagic APIs (FFI boundary).
- CMake orchestrates compilation of `sources/` into `libmagicxx` (shared/static), links against libmagic and libgnurx.
- Tests and examples link against the built library.
- Doxygen reads public headers to generate HTML docs.
- CI pipelines trigger CMake builds, run tests, generate docs, and deploy release artifacts.

c. Architectural patterns and principles
- Modular CMake design (separate modules for dependencies, installation, packaging).
- Single shared core component (the wrapper) with optional static linkage.
- Clear separation: public API layer vs private implementation.
- Test-driven validation (GoogleTest).
- Infrastructure as code (CI workflows + scripts directory).

d. Relevant technologies & frameworks
- C++23, libmagic C library
- CMake (with custom modules & CPack)
- GoogleTest (unit testing)
- Doxygen (documentation)
- GitHub Actions (CI/CD)
- Containerfile/Docker for build isolation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Code
    subgraph "Source Code"
        Headers["magicxx API (include/)"]:::code
        Impl["Wrapper Implementation (sources/magic.cpp)"]:::code
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Libmagic["libmagic C Library"]:::external
        GTest["GoogleTest (external/googletest/)"]:::external
        Gnurx["libgnurx (external/libgnurx/)"]:::external
    end

    %% Build System & Packaging
    subgraph "Build System & Packaging"
        CMakeCore["Top-level CMake Files"]:::build
        CMakeModules["CMake Modules & CPack"]:::build
        CMakeCore -->|"includes"| CMakeModules
    end

    %% Build Artifact
    LibArtifact["libmagicxx Library Artifact"]:::code

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["Examples (examples/)"]:::code
        Tests["Unit Tests (tests/)"]:::code
    end

    %% Documentation
    subgraph "Documentation"
        Doxygen["Doxygen Generator"]:::docs
        DocsHTML["HTML Docs (documentation/html/)"]:::docs
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        Workflows["GitHub Actions Workflows"]:::ci
        Containerfile["Container Build (Containerfile)"]:::ci
        Scripts["Release Automation Scripts (scripts/)"]:::ci
    end

    %% Relationships
    Headers -->|"compiled by"| CMakeCore
    Impl -->|"compiled by"| CMakeCore
    Libmagic -->|"linked by"| LibCore[Lib linking]:::build
    Gnurx -->|"linked by"| LibCore
    LibCore -->|"creates"| LibArtifact
    CMakeCore -->|"builds"| LibArtifact
    CMakeModules -->|"configures packaging"| LibArtifact

    LibArtifact -->|"used by"| Examples
    LibArtifact -->|"used by"| Tests

    Headers -->|"input to"| Doxygen
    Doxygen -->|"generates"| DocsHTML

    Workflows -->|"triggers"| CMakeCore
    Workflows -->|"triggers"| Tests
    Workflows -->|"triggers"| DocsHTML
    Workflows -->|"triggers"| CMakeModules
    Containerfile -->|"used in"| Workflows
    Scripts -->|"used in"| Workflows

    %% Click Events
    click Headers "https://github.com/oguztoraman/libmagicxx/tree/main/include/magicxx/"
    click Impl "https://github.com/oguztoraman/libmagicxx/blob/main/sources/magic.cpp"
    click Libmagic "https://github.com/oguztoraman/libmagicxx/tree/main/external/file/"
    click GTest "https://github.com/oguztoraman/libmagicxx/tree/main/external/googletest/"
    click Gnurx "https://github.com/oguztoraman/libmagicxx/tree/main/external/libgnurx/"
    click CMakeCore "https://github.com/oguztoraman/libmagicxx/blob/main/CMakeLists.txt"
    click CMakeCore "https://github.com/oguztoraman/libmagicxx/blob/main/CMakePresets.json"
    click CMakeModules "https://github.com/oguztoraman/libmagicxx/tree/main/cmake/"
    click Examples "https://github.com/oguztoraman/libmagicxx/tree/main/examples/"
    click Tests "https://github.com/oguztoraman/libmagicxx/tree/main/tests/"
    click DocsHTML "https://github.com/oguztoraman/libmagicxx/tree/main/documentation/html/"
    click Workflows "https://github.com/oguztoraman/libmagicxx/tree/main/.github/workflows/"
    click Containerfile "https://github.com/oguztoraman/libmagicxx/tree/main/Containerfile"
    click Scripts "https://github.com/oguztoraman/libmagicxx/tree/main/scripts/"

    %% Styles
    classDef code fill:#cfe2f3,stroke:#0366d6,stroke-width:1px;
    classDef external fill:#d9ead3,stroke:#006400,stroke-width:1px;
    classDef build fill:#fce5cd,stroke:#b45f06,stroke-width:1px;
    classDef ci fill:#d9d2e9,stroke:#5f4b8b,stroke-width:1px;
    classDef docs fill:#eeeeee,stroke:#888888,stroke-width:1px;
```
