# bernedom/si architecture

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

- Interactive diagram: https://gitdiagram.com/bernedom/si
- Repository: https://github.com/bernedom/si

## Overview

##### Project Type and Purpose
- This is a header‐only C++17 library (“SI”) that provides compile‐time, type‐safe representations of physical quantities in the International System of Units.
- It offers a set of `unit_t` templates (in `include/SI`), specialized typedefs and user-defined literals, plus detail helpers for compile‐time parsing, arithmetic and casting.
- It includes a comprehensive test suite (Catch2‐based), CI pipelines, documentation generation, and packaging via CMake/Conan.

##### High‐Level Architecture and Components
a. Core Library (Compile‐Time Engine)
- Directory: include/SI
- `unit_t` template struct
- Unit headers (e.g. length, mass, time, derived units)
- detail sub-folder: parser, operator helpers, conversion logic
- Responsibility: define units, ratios, execute arithmetic and conversions at compile time.

b. Build & Packaging Infrastructure
- Root CMakeLists.txt + CMakePresets.json + cmake/SIConfig.cmake.in
- Conan integration via conanfile.txt and CMakeDeps
- Packaging targets: install rules, cpack (optional), Conan center

c. Continuous Integration & Documentation
- .github/workflows/ci.yml – builds/tests on multiple compilers
- .github/workflows/api-doc.yml – triggers Doxygen or Sphinx API docs
- .github/workflows/codeql.yml – security/code analysis
- doc/ – installation guide, implementation details, code‐quality tools

d. Test Suite
- test/src – unit tests (base, derived, detail), compilation‐only tests, benchmarks
- Catch2 is vendored under test/include/catch2
- Installation tests under test/installation-tests

e. Consumer Integration (User Code)
- CMake FetchContent snippet shown in README
- Conan package usage

##### Relationships & Interactions
- The Core Library headers have an internal dependency on detail helpers, then expose public typedefs/literals to user code.
- Build system (CMake + Conan) reads conanfile.txt → generates CMakeDeps → drives header installation and test targets.
- CI pipelines invoke CMake builds, run tests (including compilation‐only tests), generate API docs into `si.dominikberner.ch/doc/`.
- Users consume the library via `target_link_libraries(MyApp PUBLIC SI::SI)` or FetchContent/Conan.

##### Architectural Patterns and Principles
- Header‐Only “Library as Code” pattern: no runtime binaries, only templates and inline functions.
- Single Responsibility: each unit (e.g. `length.h`, `mass.h`) encapsulates one physical quantity.
- CRTP/Type Traits: ratio and unit relationships encoded as type traits in detail/*.
- Zero‐Overhead Abstraction: same‐ratio operations compile to no runtime overhead.
- Extensive Test‐Driven Development: compilation‐failure tests ensure type safety at compile time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine
    subgraph "Core Unit Engine" 
        direction TB
        CoreEngine["unit_t template & public units\n(include/SI)"]:::coreEngine
        DetailHelpers["detail helpers\n(include/SI/detail)"]:::coreEngine
    end

    %% Build & Packaging
    subgraph "Build & Packaging Infrastructure"
        direction TB
        CMakeLists["CMakeLists.txt"]:::tooling
        CMakePresets["CMakePresets.json"]:::tooling
        SIConfig["cmake/SIConfig.cmake.in"]:::tooling
        ConanFile["conanfile.txt"]:::tooling
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        CI[".github/workflows/ci.yml"]:::tooling
        APIDoc[".github/workflows/api-doc.yml"]:::tooling
        CodeQL[".github/workflows/codeql.yml"]:::tooling
    end

    %% Documentation
    DocGen["Documentation Generator\n(doc/)"]:::documentation

    %% Test Suite
    subgraph "Test Harness"
        direction TB
        Catch2["Catch2 vendored header\n(test/include/catch2/catch.hpp)"]:::external
        BaseTests["base & derived unit tests\n(test/src/base_unit_tests,\n test/src/derived_unit_tests)"]:::external
        DetailTests["detail module tests\n(test/src/detail_tests)"]:::external
        CompilationTests["compilation-only tests\n(test/src/compilation_tests)"]:::external
        Benchmarks["benchmarks\n(test/src/benchmarks)"]:::external
        InstallationTests["installation tests\n(test/installation-tests)"]:::external
        InstallationSub["installation-test subdirectory\n(test/installation-test-subdirectory)"]:::external
    end

    %% Consumer Integration
    Consumer["Consumer Integration Examples\n(README.md)"]:::external

    %% Relationships
    DetailHelpers -->|used by| CoreEngine
    CoreEngine -->|included by| TestHarness
    BuildPackaging -->|configures & installs| CoreEngine
    CI -->|triggers build & test| BuildPackaging
    CI -->|runs tests| TestHarness
    CI -->|generates docs| DocGen
    Consumer -->|depends on| CoreEngine

    %% Click Events
    click CoreEngine "https://github.com/bernedom/si/tree/main/include/SI"
    click DetailHelpers "https://github.com/bernedom/si/tree/main/include/SI/detail"
    click CMakeLists "https://github.com/bernedom/si/blob/main/CMakeLists.txt"
    click CMakePresets "https://github.com/bernedom/si/blob/main/CMakePresets.json"
    click SIConfig "https://github.com/bernedom/si/blob/main/cmake/SIConfig.cmake.in"
    click ConanFile "https://github.com/bernedom/si/blob/main/conanfile.txt"
    click CI "https://github.com/bernedom/si/blob/main/.github/workflows/ci.yml"
    click APIDoc "https://github.com/bernedom/si/blob/main/.github/workflows/api-doc.yml"
    click CodeQL "https://github.com/bernedom/si/blob/main/.github/workflows/codeql.yml"
    click DocGen "https://github.com/bernedom/si/tree/main/doc/"
    click Catch2 "https://github.com/bernedom/si/blob/main/test/include/catch2/catch.hpp"
    click BaseTests "https://github.com/bernedom/si/tree/main/test/src/base_unit_tests"
    click DetailTests "https://github.com/bernedom/si/tree/main/test/src/detail_tests"
    click CompilationTests "https://github.com/bernedom/si/tree/main/test/src/compilation_tests"
    click Benchmarks "https://github.com/bernedom/si/tree/main/test/src/benchmarks"
    click InstallationTests "https://github.com/bernedom/si/tree/main/test/installation-tests"
    click InstallationSub "https://github.com/bernedom/si/tree/main/test/installation-test-subdirectory"
    click Consumer "https://github.com/bernedom/si/blob/main/README.md"

    %% Styles
    classDef coreEngine fill:#8FBFE0,stroke:#0366d6,color:#000
    classDef tooling fill:#A6E3A1,stroke:#228B22,color:#000
    classDef documentation fill:#F9E79F,stroke:#D4AC0D,color:#000
    classDef external fill:#F5CBA7,stroke:#CD5C5C,color:#000
```
