# boostorg/units architecture

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

- Interactive diagram: https://gitdiagram.com/boostorg/units
- Repository: https://github.com/boostorg/units

## Overview

##### Main Components
a. Core Library
- /boost/units (all headers: base dimensions, base units, derived units, systems, conversions, quantity, etc.)
- detail/ sub-directory (internal implementation)
b. Build System
- CMakeLists.txt
- Boost.Build files (build.jam, Jamfiles in test/, doc/, example/)
- config scripts (covscan.sh)
c. Documentation Pipeline
- doc/ (QuickBook sources)
- images/
- index.html (output)
d. Examples
- example/ (sample C++ programs illustrating usage)
e. Tests
- test/ (unit tests exercising compile-time and runtime correctness)
- test_headers/ (header-only self-containment tests)
- tutorial/ (tutorial code)
f. Continuous Integration
- Travis CI (.travis.yml)
- AppVeyor (appveyor.yml)
- Coverity Scan integration

##### Relationships and Data Flows
- Build System orchestrates:
- Compilation of examples and tests
- Generation of documentation from QuickBook sources
- Packaging of include/ files
- CI pipelines trigger Build System on push to master/develop, run tests, build docs, report status.

##### Architectural Patterns & Design Principles
- Header-Only Library: all code resides in include/ and is instantiated at compile time—no binary library produced.
- Metaprogramming: heavy use of TMP in detail/ and dimension/unit definitions.
- Modular Organization:
- Base dimensions and units (angle, length, mass, time…)
- Physical dimensions (force, energy, power…)
- Systems (SI, CGS, Imperial, US, astronomical…)
- Conversion utilities
- I/O support
- Extensibility Points: Users can add new units or systems by dropping headers into include/boost/units/base_units or by providing custom dimensions.

##### Technologies & External Dependencies
- C++14/C++17 compiler
- Boost.Build (bjam) and CMake for multi-platform build
- QuickBook for documentation
- Travis CI and AppVeyor for CI
- Coverity Scan for static analysis
- Optional: covscan.sh for Coverity scripting

##### Detail Level
- Essential components and flows: library headers, build, tests, docs, CI.
- Avoid clutter: show representative examples of units (e.g., SI base units, derived dimensions) rather than listing dozens of headers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System" 
        BS_CMake["CMakeLists.txt"]:::build
        BS_BJam["build.jam"]:::build
        BS_TestJam["test/Jamfile.v2"]:::build
        BS_DocJam["doc/Jamfile.v2"]:::build
        BS_ExJam["example/Jamfile.v2"]:::build
        BS_CovScan["covscan.sh"]:::build
    end

    %% Core Library
    subgraph "Core Library" 
        CL_Headers["include/boost/units"]:::library
        CL_Detail["include/boost/units/detail"]:::library
    end

    %% Documentation Pipeline
    subgraph "Documentation" 
        DOC_QBK["doc/units.qbk"]:::docs
        DOC_Images["images/"]:::docs
        DOC_HTML["index.html"]:::docs
    end

    %% Examples
    subgraph "Examples" 
        EX_Code["example/"]:::examples
    end

    %% Tests
    subgraph "Tests" 
        TEST_Unit["test/"]:::tests
        TEST_Hdrs["test_headers/"]:::tests
        TEST_Tut["tutorial/"]:::tests
    end

    %% Continuous Integration
    subgraph "Continuous Integration" 
        CI_Trav[".travis.yml"]:::ci
        CI_AppV["appveyor.yml"]:::ci
        CI_Cov["Coverity Scan"]:::ci
    end

    %% Relationships
    CI_Trav -->|"triggers build"| BS_CMake
    CI_AppV -->|"triggers build"| BS_CMake
    CI_Cov -->|"invokes covscan.sh"| BS_CovScan

    BS_CMake -->|"orchestrates"| CL_Headers
    BS_CMake -->|"orchestrates"| CL_Detail
    BS_CMake -->|"build tests"| TEST_Unit
    BS_CMake -->|"build tests"| TEST_Hdrs
    BS_CMake -->|"build examples"| EX_Code
    BS_CMake -->|"generate docs"| DOC_QBK
    BS_CMake -->|"package headers"| CL_Headers

    CL_Headers -->|"included by tests"| TEST_Unit
    CL_Headers -->|"included by examples"| EX_Code
    CL_Headers -->|"included by tutorials"| TEST_Tut

    DOC_QBK -->|"produces"| DOC_HTML
    DOC_Images -->|"used in"| DOC_HTML

    %% Click events
    click CL_Headers "https://github.com/boostorg/units/tree/develop/include/boost/units"
    click CL_Detail "https://github.com/boostorg/units/tree/develop/include/boost/units/detail"
    click BS_CMake "https://github.com/boostorg/units/blob/develop/CMakeLists.txt"
    click BS_BJam "https://github.com/boostorg/units/blob/develop/build.jam"
    click BS_TestJam "https://github.com/boostorg/units/blob/develop/test/Jamfile.v2"
    click BS_DocJam "https://github.com/boostorg/units/blob/develop/doc/Jamfile.v2"
    click BS_ExJam "https://github.com/boostorg/units/blob/develop/example/Jamfile.v2"
    click BS_CovScan "https://github.com/boostorg/units/blob/develop/covscan.sh"
    click DOC_QBK "https://github.com/boostorg/units/blob/develop/doc/units.qbk"
    click DOC_HTML "https://github.com/boostorg/units/blob/develop/index.html"
    click DOC_Images "https://github.com/boostorg/units/tree/develop/images/"
    click EX_Code "https://github.com/boostorg/units/tree/develop/example/"
    click TEST_Unit "https://github.com/boostorg/units/tree/develop/test/"
    click TEST_Hdrs "https://github.com/boostorg/units/tree/develop/test_headers/"
    click TEST_Tut "https://github.com/boostorg/units/tree/develop/tutorial/"
    click CI_Trav "https://github.com/boostorg/units/blob/develop/.travis.yml"
    click CI_AppV "https://github.com/boostorg/units/blob/develop/appveyor.yml"

    %% Styles
    classDef library fill:#cce5ff,stroke:#004085,color:#004085
    classDef build fill:#d4edda,stroke:#155724,color:#155724
    classDef docs fill:#ffe5b4,stroke:#cc8400,color:#cc8400
    classDef tests fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef examples fill:#fff3cd,stroke:#856404,color:#856404
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
