# clusterchallenge/universal architecture

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

- Interactive diagram: https://gitdiagram.com/clusterchallenge/universal
- Repository: https://github.com/clusterchallenge/universal

## Overview

##### Project type and purpose
- This is a header-only C++ template library—“Universal”—that provides a rich set of parameterized number systems (posits, elasts, floats, integers, decimals, etc.), command-line tools, example applications, benchmarks, documentation, and CI/CD integration. Its primary purpose is to enable mixed-precision arithmetic research, educational demos, and production use of alternative number formats.

a. Core Library
- /universal: all header files for static and elastic number systems
- src/internal (optional): reference implementations
b. Build System
- CMakeLists.txt, tools/cmake/: generates build targets for library, tools, tests, benchmarks, docs
- .devcontainer/, docker/: scripts and Dockerfiles for containerized builds
c. Command-Line Tools
- tools/cmd/* → executables like “half”, “posit”, “ieee” that inspect number types
- c_api/shim & c_api/pure_c → C-language bindings
d. Examples & Demos
- applications/: numerical examples demonstrating accuracy, performance, roots, PDE, ODE, mixed precision
- education/: educational demos per number system
- playground/: scratch/test code
e. Benchmarks
- benchmark/: performance, accuracy, reproducibility, energy, range
f. Verification & Tests
- static/*/CMakeFiles/*_test: regression suites per number system
- make test / CTest → runs all enabled tests
g. Documentation & Assets
- docs/: markdown, PDFs, images, tutorials
- README.md, PURPOSE.md, CITATION.cff
h. CI/CD & Quality
- .github/workflows/cmake.yml → builds, regression tests, coverage reports
- Codacy, Coveralls, FOSSA badges
i. Distribution
- bin/: prebuilt executables and scripts
- Docker Hub: stillwater/universal container pull
- install scripts: install_cmake.sh, cmake install targets

##### Relationships and interactions
- Build System ▶ Core Library & Command-Line Tools & Tests & Examples & Benchmarks & Docs
- Core Library ▶ consumed by Command-Line Tools, Examples, Benchmarks, Education, C API
- Command-Line Tools & C API ▶ packaged into bin/ and Docker images
- Examples & Benchmarks ▶ link against Core Library via CMake targets
- Verification Tests ▶ validate Core Library and each number system
- CI/CD ▶ triggers Build System; reports status to GitHub, Codacy, Coveralls, FOSSA
- Dockerfiles ▶ use Build System to produce container images for quick starts

##### Architectural patterns & principles
- Modular CMake targets: each number system or functional group is its own CMake project for fast builds
- Header-only library: zero runtime linkage, template instantiation at compile time
- Single source of truth: include/universal headers drive all functionality
- Plug-in style CLI tools: share the same template infrastructure
- Containerized development: .devcontainer + docker scripts for reproducible build environments
- CI-as-code: GitHub Actions workflows define build & test pipelines

##### Technologies and frameworks
- C++20 templates
- CMake v3.23+
- Docker
- GitHub Actions for CI
- Codacy, Coveralls, FOSSA for quality and license scanning
- Bash scripts for build and install automation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Core Library"
        direction TB
        CL1["include/universal"]:::core
        CL2["internal/"]:::core
    end
    click CL1 "https://github.com/clusterchallenge/universal/tree/main/include/universal"
    click CL2 "https://github.com/clusterchallenge/universal/tree/main/internal/"

    subgraph "Build & CI/CD"
        direction TB
        BS1["CMakeLists.txt"]:::build
        BS2["tools/cmake/"]:::build
        BS3[".devcontainer/, docker/"]:::build
        CI["CI/CD Workflow"]:::build
    end
    click BS1 "https://github.com/clusterchallenge/universal/blob/main/CMakeLists.txt"
    click BS2 "https://github.com/clusterchallenge/universal/tree/main/tools/cmake/"
    click BS3 "https://github.com/clusterchallenge/universal/tree/main/.devcontainer/"
    click BS3 "https://github.com/clusterchallenge/universal/tree/main/docker/"
    click CI "https://github.com/clusterchallenge/universal/blob/main/.github/workflows/cmake.yml"

    subgraph "Tools & APIs"
        direction TB
        CT["tools/cmd/"]:::tools
        CAS["c_api/shim/"]:::tools
        CAP["c_api/pure_c/"]:::tools
    end
    click CT "https://github.com/clusterchallenge/universal/tree/main/tools/cmd/"
    click CAS "https://github.com/clusterchallenge/universal/tree/main/c_api/shim/"
    click CAP "https://github.com/clusterchallenge/universal/tree/main/c_api/pure_c/"

    subgraph "Examples & Benchmarks"
        direction TB
        EX1["applications/"]:::examples
        EX2["education/"]:::examples
        EX3["playground/"]:::examples
        BM["benchmark/"]:::examples
    end
    click EX1 "https://github.com/clusterchallenge/universal/tree/main/applications/"
    click EX2 "https://github.com/clusterchallenge/universal/tree/main/education/"
    click EX3 "https://github.com/clusterchallenge/universal/tree/main/playground/"
    click BM "https://github.com/clusterchallenge/universal/tree/main/benchmark/"

    subgraph "Verification & Tests"
        direction TB
        VT1["include/universal/verification/"]:::build
        VT2["c_api/shim/test/"]:::build
        VT3["c_api/pure_c/test/"]:::build
    end
    click VT1 "https://github.com/clusterchallenge/universal/tree/main/include/universal/verification/"
    click VT2 "https://github.com/clusterchallenge/universal/tree/main/c_api/shim/test/"
    click VT3 "https://github.com/clusterchallenge/universal/tree/main/c_api/pure_c/test/"

    subgraph "Documentation & Assets"
        direction TB
        DOCS["docs/"]:::docs
        RMD["README.md"]:::docs
        PMD["PURPOSE.md"]:::docs
        CFF["CITATION.cff"]:::docs
    end
    click DOCS "https://github.com/clusterchallenge/universal/tree/main/docs/"
    click RMD "https://github.com/clusterchallenge/universal/blob/main/README.md"
    click PMD "https://github.com/clusterchallenge/universal/blob/main/PURPOSE.md"
    click CFF "https://github.com/clusterchallenge/universal/blob/main/CITATION.cff"

    subgraph "Distribution"
        direction TB
        BIN["bin/, install_cmake.sh"]:::dist
        DFR["Dockerfile"]:::dist
    end
    click BIN "https://github.com/clusterchallenge/universal/tree/main/bin/"
    click BIN "https://github.com/clusterchallenge/universal/blob/main/install_cmake.sh"
    click DFR "https://github.com/clusterchallenge/universal/tree/main/Dockerfile"

    GH["GitHub Actions"]:::cloud
    DBADGES["Codacy, Coveralls, FOSSA"]:::cloud
    DH["Docker Hub"]:::cloud

    GH -->|"triggers→"| BS1
    BS1 -->|"builds→ Core Library"| CL1
    BS1 -->|"builds→ Tools & APIs"| CT
    BS1 -->|"builds→ Examples & Benchmarks"| EX1
    BS1 -->|"builds→ Tests"| VT1
    BS1 -->|"builds→ Docs & Assets"| DOCS

    CL1 -->|"consumed by"| CT
    CL1 -->|"consumed by"| EX1
    CL1 -->|"consumed by"| BM

    CT -->|"packages→"| BIN
    BS3 -->|"container build→"| DFR
    BS3 -->|"push→"| DH

    GH -->|"reports→"| DBADGES

    classDef core fill:#D0E4FD,stroke:#036,color:#036
    classDef build fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef tools fill:#FEEFB3,stroke:#9F6000,color:#9F6000
    classDef examples fill:#E0B0FF,stroke:#7B1FA2,color:#7B1FA2
    classDef docs fill:#F0F0F0,stroke:#666,color:#333
    classDef dist fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef cloud fill:#CCECFF,stroke:#3399FF,color:#3399FF
```
