# boostorg/boost architecture

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

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

## Overview

This repository is the Boost C++ Libraries superproject: a large, multi-library source distribution rather than a single application. Its architecture is centered on reusable C++ components, with shared build, documentation, validation, and release tooling around them.

1. **Core product layer: `libs/`**
   The main payload lives under `libs/*`. Each subdirectory is an individual Boost library or related module, typically with its own headers, tests, docs, and build metadata. Examples include `asio`, `filesystem`, `json`, `thread`, `python`, `program_options`, `variant`, and many others.

2. **Library boundary model**
   Most Boost libraries are designed as independently consumable components, often header-only or with a small compiled part. The repository structure reflects that: the library directories are the source-of-truth boundaries, not a single shared application layer.

3. **Common build and integration layer**
   Build orchestration is shared across the repo through `Jamroot`, `Jamfile.v2`, `boost-build.jam`, `boostcpp.jam`, and the root `CMakeLists.txt`. This gives the project dual build support: Boost.Build/B2 remains central, while CMake is supported for broader ecosystem integration.

4. **Tooling layer: `tools/`**
   `tools/` contains developer and release utilities such as `boostdep`, `boostbook`, `quickbook`, `inspect`, `bcp`, `check_build`, and `cmake` helpers. These tools support dependency analysis, documentation generation, packaging, and build validation across the library collection.

5. **Documentation system: `doc/`**
   The `doc/` tree contains the project-wide documentation pipeline, including source inputs, HTML/PDF outputs, test fixtures, and styling assets. Documentation is generated from BoostBook/Quickbook sources into publishable formats, with a separate documentation build flow from library compilation.

6. **Documentation as a first-class artifact**
   The repo includes prebuilt docs under `doc/html` and `doc/pdf`, plus test cases in `doc/test`. This indicates documentation is treated as a build artifact with regression checks, not just static text checked into the repo.

7. **Status, quality, and release gating: `status/`**
   The `status/` directory holds automated conformance and regression infrastructure, including expected results, failure markup, and inspection scripts. This layer is used to track library health and detect breakage across the broad library set.

8. **Continuous integration and release automation**
   CI is externalized through `.github/workflows/*`, `.circleci/*`, `.travis.yml`, and `appveyor.yml`. These pipelines validate builds across platforms and toolchains, and the release workflow (`release-cmake.yml`) suggests packaging and release verification are part of the repo’s operational flow.

9. **Cross-platform support as an architectural constraint**
   The presence of Windows, Linux, and macOS-oriented CI plus Boost’s portable C++ mission means portability is a structural concern. Build scripts, tests, and library code are organized to keep platform-specific differences isolated.

10. **Repository bootstrap and distribution support**
    Scripts like `bootstrap.sh`, `bootstrap.bat`, `INSTALL`, and the top-level `README.md` support first-time setup and consumption. This is a source distribution designed to be built from checkout, with standardized entry points for users and contributors.

11. **External dependency management**
    The repository uses `.gitmodules`, indicating some parts may be maintained as submodules or have external source dependencies. In architectural terms, that means some workflows rely on synchronized external components rather than everything living in one flat source tree.

12. **Overall data flow**
    Source code in `libs/` and tooling in `tools/` feed the build system (`Jamroot`/CMake). The build produces library artifacts and test results, while the documentation pipeline transforms docs sources in `doc/` into HTML/PDF outputs. CI runs these flows on multiple platforms and publishes verification signals used for release readiness.

13. **How to diagram it**
    A good architecture diagram should show:
    - a central “Boost library collection” block containing many independent library modules,
    - shared build orchestration around it,
    - documentation generation as a parallel pipeline,
    - status/testing as a quality gate,
    - and CI/release automation as external execution environments.

In short, this repo is a platform for distributing and validating many independent C++ libraries, with strong shared infrastructure for building, documenting, and continuously verifying them across platforms.

Main entry points: [`libs`](https://github.com/boostorg/boost/tree/master/libs) (Library set), [`doc`](https://github.com/boostorg/boost/tree/master/doc) (Docs pipeline), [`.github/workflows/ci.yml`](https://github.com/boostorg/boost/blob/master/.github/workflows/ci.yml) (CI workflows), [`tools`](https://github.com/boostorg/boost/tree/master/tools) (Tooling set)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core libraries"]
  node_libs_root["Library set<br/>library collection"]
  node_libs_core["Core libs<br/>fundamental libraries"]
  node_libs_runtime["Runtime libs<br/>runtime / concurrency"]
  node_libs_data["Data libs<br/>data / containers"]
  node_libs_meta["Meta libs<br/>templates / metaprogramming"]
  node_libs_text["Text libs<br/>text / formatting"]
  node_libs_dist["Dist libs<br/>distribution / interop"]
end

subgraph group_infra["Shared infrastructure"]
  node_build_root["Build root<br/>build orchestration"]
  node_build_cmake["CMake entry<br/>cmake root<br/>[CMakeLists.txt]"]
  node_bootstrap["Bootstrap<br/>setup scripts<br/>[bootstrap.sh]"]
end

subgraph group_docs["Documentation"]
  node_doc_root["Docs pipeline<br/>documentation system"]
  node_doc_src["Doc sources<br/>documentation sources"]
  node_doc_test["Doc tests<br/>doc regression"]
end

subgraph group_quality["Quality gates"]
  node_status_root["Status checks<br/>regression gate"]
end

subgraph group_automation["CI / release"]
  node_ci_root["CI workflows<br/>automation<br/>[ci.yml]"]
end

subgraph group_tools["Tools"]
  node_tools_root["Tooling set<br/>developer tools"]
  node_boostdep["Boostdep<br/>dependency analyzer"]
  node_quickbook["Quickbook<br/>doc source tool"]
  node_boostbook["BoostBook<br/>doc generator"]
end

node_build_root -->|"builds"| node_libs_root
node_build_cmake -->|"configures"| node_libs_root
node_bootstrap -->|"prepares"| node_build_root
node_libs_root -->|"includes"| node_libs_core
node_libs_root -->|"includes"| node_libs_runtime
node_libs_root -->|"includes"| node_libs_data
node_libs_root -->|"includes"| node_libs_meta
node_libs_root -->|"includes"| node_libs_text
node_libs_root -->|"includes"| node_libs_dist
node_tools_root -->|"provides"| node_boostdep
node_tools_root -->|"provides"| node_quickbook
node_tools_root -->|"provides"| node_boostbook
node_tools_root -->|"supports"| node_status_root
node_doc_root -->|"contains"| node_doc_src
node_doc_root -->|"contains"| node_doc_test
node_doc_root -->|"uses"| node_boostbook
node_doc_root -->|"uses"| node_quickbook
node_status_root -->|"checks"| node_libs_root
node_status_root -->|"verifies"| node_build_root
node_ci_root -->|"runs"| node_build_root
node_ci_root -->|"publishes"| node_doc_root
node_ci_root -->|"gates"| node_status_root
node_ci_root -->|"tests"| node_bootstrap

click node_libs_root "https://github.com/boostorg/boost/tree/master/libs"
click node_libs_core "https://github.com/boostorg/boost/tree/master/libs/core"
click node_libs_runtime "https://github.com/boostorg/boost/tree/master/libs/asio"
click node_libs_data "https://github.com/boostorg/boost/tree/master/libs/array"
click node_libs_meta "https://github.com/boostorg/boost/tree/master/libs/type_traits"
click node_libs_text "https://github.com/boostorg/boost/tree/master/libs/format"
click node_libs_dist "https://github.com/boostorg/boost/tree/master/libs/filesystem"
click node_build_root "https://github.com/boostorg/boost/tree/master/Jamroot"
click node_build_cmake "https://github.com/boostorg/boost/blob/master/CMakeLists.txt"
click node_bootstrap "https://github.com/boostorg/boost/blob/master/bootstrap.sh"
click node_tools_root "https://github.com/boostorg/boost/tree/master/tools"
click node_boostdep "https://github.com/boostorg/boost/tree/master/tools/boostdep"
click node_quickbook "https://github.com/boostorg/boost/tree/master/tools/quickbook"
click node_boostbook "https://github.com/boostorg/boost/tree/master/tools/boostbook"
click node_status_root "https://github.com/boostorg/boost/tree/master/status"
click node_doc_root "https://github.com/boostorg/boost/tree/master/doc"
click node_doc_src "https://github.com/boostorg/boost/tree/master/doc/src"
click node_doc_test "https://github.com/boostorg/boost/tree/master/doc/test"
click node_ci_root "https://github.com/boostorg/boost/blob/master/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_libs_root,node_libs_core,node_libs_runtime,node_libs_data,node_libs_meta,node_libs_text,node_libs_dist toneBlue
class node_build_root,node_build_cmake,node_bootstrap toneAmber
class node_doc_root,node_doc_src,node_doc_test toneMint
class node_status_root toneRose
class node_ci_root toneIndigo
class node_tools_root,node_boostdep,node_quickbook,node_boostbook toneTeal
```

## Components

### Core libraries

Independent Boost library modules under libs/.

- [Library set](https://github.com/boostorg/boost/tree/master/libs): library collection · The main Boost source distribution of independently consumable C++ libraries. · `libs`
- [Core libs](https://github.com/boostorg/boost/tree/master/libs/core): fundamental libraries · Common building blocks and portability primitives used by many other Boost components. · `libs/core`
- [Runtime libs](https://github.com/boostorg/boost/tree/master/libs/asio): runtime / concurrency · Execution, threading, networking, and system-facing libraries. · `libs/asio`
- [Data libs](https://github.com/boostorg/boost/tree/master/libs/array): data / containers · Containers, parsing, numeric, and data structure oriented libraries. · `libs/array`
- [Meta libs](https://github.com/boostorg/boost/tree/master/libs/type_traits): templates / metaprogramming · Template metaprogramming and type-introspection libraries. · `libs/type_traits`
- [Text libs](https://github.com/boostorg/boost/tree/master/libs/format): text / formatting · String processing, lexical conversion, and formatting libraries. · `libs/format`
- [Dist libs](https://github.com/boostorg/boost/tree/master/libs/filesystem): distribution / interop · Serialization, filesystem, Python, and other broader integration libraries. · `libs/filesystem`

### Shared infrastructure

Repo-wide build and bootstrap entry points.

- [Build root](https://github.com/boostorg/boost/tree/master/Jamroot): build orchestration · Top-level Boost.Build and CMake entry points that coordinate repo-wide builds. · `Jamroot`
- [CMake entry](https://github.com/boostorg/boost/blob/master/CMakeLists.txt): cmake root · Repository-level CMake configuration for external build ecosystem integration. · `CMakeLists.txt`
- [Bootstrap](https://github.com/boostorg/boost/blob/master/bootstrap.sh): setup scripts · Initial setup and distribution scripts for configuring the repository build. · `bootstrap.sh`

### Documentation

Documentation sources, generated outputs, and doc tooling.

- [Docs pipeline](https://github.com/boostorg/boost/tree/master/doc): documentation system · Project-wide documentation sources, tests, and generated outputs. · `doc`
- [Doc sources](https://github.com/boostorg/boost/tree/master/doc/src): documentation sources · Primary BoostBook and stylesheet sources for documentation generation. · `doc/src`
- [Doc tests](https://github.com/boostorg/boost/tree/master/doc/test): doc regression · Documentation formatting and gold-file regression tests. · `doc/test`

### Quality gates

Status, regression, and validation infrastructure.

- [Status checks](https://github.com/boostorg/boost/tree/master/status): regression gate · Automated conformance, expected-results, and inspection infrastructure. · `status`

### CI / release

External automation and platform validation.

- [CI workflows](https://github.com/boostorg/boost/blob/master/.github/workflows/ci.yml): automation · External continuous integration and release automation across platforms. · `.github/workflows/ci.yml`

### Tools

Developer and release utilities.

- [Tooling set](https://github.com/boostorg/boost/tree/master/tools): developer tools · Utilities for dependency analysis, documentation, inspection, and packaging. · `tools`
- [Boostdep](https://github.com/boostorg/boost/tree/master/tools/boostdep): dependency analyzer · Analyzes library dependencies across the Boost source tree. · `tools/boostdep`
- [Quickbook](https://github.com/boostorg/boost/tree/master/tools/quickbook): doc source tool · Transforms Boost documentation sources into publishable doc inputs. · `tools/quickbook`
- [BoostBook](https://github.com/boostorg/boost/tree/master/tools/boostbook): doc generator · Documentation generation and formatting support for BoostBook sources. · `tools/boostbook`

## Connections

- Build root → Library set: builds · Boost.Build orchestrates the library collection.
- CMake entry → Library set: configures · CMake provides an alternate repo-wide build entry.
- Bootstrap → Build root: prepares · Bootstrap scripts initialize the build environment.
- Library set → Core libs: includes · The library set contains core foundational modules.
- Library set → Runtime libs: includes · The library set contains runtime and concurrency modules.
- Library set → Data libs: includes · The library set contains data-structure and container modules.
- Library set → Meta libs: includes · The library set contains metaprogramming modules.
- Library set → Text libs: includes · The library set contains string and formatting modules.
- Library set → Dist libs: includes · The library set contains integration and distribution modules.
- Tooling set → Boostdep: provides · Dependency analysis is one of the central repo tools.
- Tooling set → Quickbook: provides · Quickbook is a major documentation source tool.
- Tooling set → BoostBook: provides · BoostBook supports documentation generation.
- Tooling set → Status checks: supports · Tooling feeds validation and inspection workflows.
- Docs pipeline → Doc sources: contains · Documentation sources live under doc/src.
- Docs pipeline → Doc tests: contains · Documentation regression tests live under doc/test.
- Docs pipeline → BoostBook: uses · The doc pipeline depends on BoostBook generation support.
- Docs pipeline → Quickbook: uses · The doc pipeline depends on Quickbook source processing.
- Status checks → Library set: checks · Status tooling validates the library collection.
- Status checks → Build root: verifies · Status checks exercise the shared build system.
- CI workflows → Build root: runs · CI executes the primary build orchestration.
- CI workflows → Docs pipeline: publishes · CI builds and validates documentation artifacts.
- CI workflows → Status checks: gates · CI consumes status results for readiness checks.
- CI workflows → Bootstrap: tests · Automation validates repo bootstrap and setup flows.
