# llnl/units architecture

> Architecture diagram of the GitHub repository llnl/units, 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/llnl/units
- Repository: https://github.com/llnl/units

## Overview

##### Project type and purpose
- This is a C++ runtime units‐of‐measurement library that provides:
- A core header‐only + compiled-object “units” library (units/)
- A command-line converter app (converter/)
- A Python extension module (python/units_llnl)
- A lightweight HTTP conversion web service (webserver/)
- Full documentation (docs/) and testing/fuzzing harnesses

##### File structure
- Top‐level build: CMakeLists.txt drives the build of all components.
- Directories:
- units/ – core library sources & headers
- converter/ – CLI tool linking to core library
- python/ – CMake wrapper building Python extension units_llnl
- webserver/ – simple HTTP server binary, static HTML pages, Dockerfile
- test/ – C++ unit tests (googletest), example & find_package tests
- FuzzTargets/ – fuzz inputs, harnesses, Dockerfile for libFuzzer
- ThirdParty/ – vendored headers (CLI11, tinyxml2, googletest, CMake macros)
- docs/ – Sphinx sources, conf.py, make scripts for ReadTheDocs
- .ci/, .circleci/, .github/ – CI/CD pipelines (Azure DevOps, CircleCI, GitHub Actions)
- config/ – lint, format, spellcheck, code coverage CMake helpers

##### README for additional insights
- Describes runtime unit representation, string conversions, measurement types, Python wrapper, converter app, example usage.
- Builds as static/shared library targets (units::units, units::header_only).
- CI workflows for build/test/coverage/docs/deployment.
- Docker images published for converter and possibly webserver.

##### Elements
- Clear labels for every component and artifact (e.g. units::units, converter binary, units_llnl.so)
- Blue rectangles for core/library modules
- Green rectangles for consumer applications (CLI, Python, Web)
- Orange rectangles for infrastructure (Build System, CI/CD)
- Clouds for external services (GitHub, Azure DevOps)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD Pipelines"
        Azure["Azure DevOps"]:::external
        CircleCI["CircleCI"]:::external
        GitHubActions["GitHub Actions"]:::external
    end
    Azure --> BuildSystem
    CircleCI --> BuildSystem
    GitHubActions --> BuildSystem

    BuildSystem["CMake Build System"]:::infra
    click BuildSystem "https://github.com/llnl/units/blob/main/CMakeLists.txt"
    click BuildSystem "https://github.com/llnl/units/tree/main/config/"

    ThirdParty["Third-Party Dependencies"]:::infra
    click ThirdParty "https://github.com/llnl/units/tree/main/ThirdParty/"
    ThirdParty --> BuildSystem

    Docs["Documentation Generator"]:::infra
    click Docs "https://github.com/llnl/units/tree/main/docs/"
    BuildSystem --> Docs

    subgraph "Consumers"
        Converter["Converter CLI App"]:::consumer
        PythonExt["Python Extension Module"]:::consumer
        WebServer["Web Server Service"]:::consumer
        TestSuite["Test Suite"]:::consumer
        FuzzHarness["Fuzz Harness"]:::consumer
    end

    Converter --> Core
    PythonExt --> Core
    WebServer --> Core
    TestSuite --> Core
    FuzzHarness --> Core

    BuildSystem --> Converter
    BuildSystem --> PythonExt
    BuildSystem --> WebServer
    BuildSystem --> TestSuite
    BuildSystem --> FuzzHarness
    BuildSystem --> Core

    Core["Core Units Library"]:::core
    click Core "https://github.com/llnl/units/tree/main/units/"

    click Converter "https://github.com/llnl/units/blob/main/converter/converter.cpp"
    click Converter "https://github.com/llnl/units/blob/main/converter/CMakeLists.txt"

    click PythonExt "https://github.com/llnl/units/blob/main/python/units_llnl/__init__.py"
    click PythonExt "https://github.com/llnl/units/blob/main/python/units_python.cpp"

    click WebServer "https://github.com/llnl/units/blob/main/webserver/unit_web_server.cpp"
    click WebServer "https://github.com/llnl/units/blob/main/webserver/CMakeLists.txt"
    click WebServer "https://github.com/llnl/units/tree/main/webserver/Dockerfile"
    click WebServer "https://github.com/llnl/units/blob/main/webserver/index.html"

    click TestSuite "https://github.com/llnl/units/tree/main/test/"
    click FuzzHarness "https://github.com/llnl/units/tree/main/FuzzTargets/"

    subgraph "Artifact Repositories"
        PyPI["PyPI"]:::repo
        DockerHub["DockerHub"]:::repo
        ReadTheDocs["ReadTheDocs"]:::repo
    end

    PythonExt -->|"wheel"| PyPI
    Converter -->|"Docker image"| DockerHub
    FuzzHarness -->|"Docker image"| DockerHub
    WebServer -->|"Docker image"| DockerHub
    Docs -->|"docs site"| ReadTheDocs

    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef consumer fill:#d4edda,stroke:#333,stroke-width:1px
    classDef infra fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef repo fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px
```
