# woven-by-toyota/arene-base architecture

> Architecture diagram of the GitHub repository woven-by-toyota/arene-base, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/woven-by-toyota/arene-base
- Repository: https://github.com/woven-by-toyota/arene-base

## Overview

1. `arene-base` is a Bazel-managed C++14 library stack, not an application. The repository is organized as many small Bazel targets under `arene/base/...` plus a separate `stdlib/...` implementation layer, with tests, docs, and build tooling around them.

2. The core product boundary is `arene/base`: a collection of low-level reusable facilities for safety-critical C++ code. Most subpackages are header-centric libraries, with a few `.cpp` files where runtime behavior or platform integration is needed. Each feature area has its own `BUILD.bazel` and dedicated tests.

3. The `arene/base` subsystems are layered from foundational primitives upward. Lower-level building blocks such as `type_traits`, `utility`, `memory`, `iterator`, `compiler_support`, and `functional` are used by higher-level facilities like `containers` (`inline_container`, `array`, `optional`, `variant`, `result`), `strings`, `math`, `span/mdspan`, `units`, `filesystem`, and synchronization primitives.

4. Several packages represent “safe alternatives” to standard C++ facilities: `pointer` (`non_null`, `non_owning_ptr`), `result`, `scope_guard`, `monostate`, `semantic_version`, `source_location`, `byte`, `bit`, `endian`, and `contracts`. These are designed as reusable policy-bearing primitives rather than domain services.

5. Concurrency and OS-facing functionality is isolated into a smaller set of runtime-heavy components: `mutex`, `synchronization` (`barrier`, `latch`, `manual_reset_event`), and `filesystem` (`file_handle`, `directory_handle`, temporary-directory helpers, scoped directory changes). These have explicit `.cpp` implementations and platform-specific branches, unlike the mostly header-only utility layers.

6. The repository includes a separate `stdlib` subtree that acts as a cut-down standard library implementation or shim. It exposes standard-looking headers and `stdlib_detail` internals, and it is intentionally decoupled so `arene/base` can be built either against the toolchain’s standard library or against this repo’s `//stdlib` target.

7. Build-time configuration is a major architectural boundary. `configs/`, `rules/`, `bazel_lib/`, and `extensions/` provide Bazel macros, transitions, and platform/compiler selection logic. The repo’s variants include exception-enabled/disabled code paths, sanitizer/coverage hooks, and stdlib selection; this is how the same API surface can map to different implementations.

8. Platform-specific implementations are handled as alternate source files or internal headers rather than scattered conditionals. Examples include exception-aware vs exception-free code in `array`, `optional`, `variant`, `contracts`, and platform-specific filesystem helpers. This keeps policy decisions at the build/config layer and implementation details inside each package.

9. Testing is first-class and mirrors the library structure. Each package has its own test target set, including normal unit tests, death tests, compile-error tests, and some property-based or self-checking scripts. The repo also has `testlibs/` for reusable test support: `minitest`, dummy `gtest/gmock`, and assorted utilities used to validate the library’s behavior across configurations.

10. `docs/` is a generated/packaged consumer-facing layer, with user guides, API docs, examples, and architecture diagrams. The examples are build targets too, so documentation is tied to compilable code. GitHub Actions are used to run public tests and publish docs to GitHub Pages, making the documentation and CI part of the delivery pipeline rather than a separate product.

Main entry points: [`arene/base`](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base) (arene/base), [`arene/base/inline_container`](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/inline_container) (containers), [`stdlib`](https://github.com/woven-by-toyota/arene-base/tree/main/stdlib) (stdlib), [`rules`](https://github.com/woven-by-toyota/arene-base/tree/main/rules) (rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_build["Build & Config"]
  node_n_build_rules["rules<br/>bazel macros"]
  node_n_build_configs["configs<br/>build config"]
  node_n_build_extensions["extensions<br/>bazel extension"]
end

subgraph group_grp_base_foundation["Foundation"]
  node_n_compiler_support["compiler support<br/>portable intrinsics"]
  node_n_type_traits["type traits<br/>template meta"]
  node_n_type_manip["type manipulation<br/>template meta"]
  node_n_utility["utility<br/>core helpers"]
  node_n_functional["functional<br/>call wrappers"]
  node_n_iterator["iterator"]
  node_n_memory["memory<br/>object lifetime"]
end

subgraph group_grp_base_facilities["Core Facilities"]
  node_n_arene_base["arene/base<br/>core library stack"]
  node_n_base_types["core types<br/>safe primitives"]
  node_n_safe_ptrs["safe pointers<br/>pointer wrappers"]
  node_n_result_optional["result & optional<br/>sum types"]
  node_n_containers["containers"]
  node_n_strings["strings<br/>string facilities"]
  node_n_math_units["math & units<br/>numeric facilities"]
  node_n_span_mdspan["span & mdspan<br/>view types"]
end

subgraph group_grp_runtime["Runtime & OS"]
  node_n_sync_os["sync & OS<br/>runtime integration"]
end

subgraph group_grp_testing["Testing & Docs"]
  node_n_testing_base["testing<br/>test support"]
  node_n_docs["docs"]
  node_n_testlibs["testlibs<br/>test fixtures"]
end

subgraph group_grp_stdlib["Stdlib Layer"]
  node_n_stdlib["stdlib"]
end

node_n_arene_base -->|"depends on"| node_n_compiler_support
node_n_arene_base -->|"depends on"| node_n_type_traits
node_n_arene_base -->|"depends on"| node_n_type_manip
node_n_arene_base -->|"depends on"| node_n_utility
node_n_arene_base -->|"depends on"| node_n_functional
node_n_arene_base -->|"depends on"| node_n_iterator
node_n_arene_base -->|"depends on"| node_n_memory
node_n_arene_base -->|"contains"| node_n_base_types
node_n_base_types -->|"includes"| node_n_safe_ptrs
node_n_base_types -->|"includes"| node_n_result_optional
node_n_base_types -->|"supports"| node_n_containers
node_n_base_types -->|"supports"| node_n_strings
node_n_base_types -->|"supports"| node_n_math_units
node_n_base_types -->|"supports"| node_n_span_mdspan
node_n_base_types -->|"supports"| node_n_sync_os
node_n_containers -->|"uses"| node_n_result_optional
node_n_containers -->|"uses"| node_n_safe_ptrs
node_n_strings -->|"uses"| node_n_utility
node_n_math_units -->|"uses"| node_n_type_traits
node_n_span_mdspan -->|"uses"| node_n_iterator
node_n_sync_os -->|"uses"| node_n_compiler_support
node_n_testing_base -->|"uses"| node_n_testlibs
node_n_docs -->|"documents"| node_n_arene_base
node_n_docs -->|"documents"| node_n_stdlib
node_n_build_rules -->|"builds"| node_n_arene_base
node_n_build_configs -->|"configures"| node_n_build_rules
node_n_build_extensions -->|"extends"| node_n_build_rules
node_n_stdlib -->|"backend for"| node_n_arene_base
node_n_stdlib -->|"mirrors"| node_n_compiler_support
node_n_testing_base -->|"tests"| node_n_arene_base

click node_n_arene_base "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base"
click node_n_build_rules "https://github.com/woven-by-toyota/arene-base/tree/main/rules"
click node_n_build_configs "https://github.com/woven-by-toyota/arene-base/tree/main/configs"
click node_n_build_extensions "https://github.com/woven-by-toyota/arene-base/tree/main/extensions"
click node_n_compiler_support "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/compiler_support"
click node_n_type_traits "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/type_traits"
click node_n_type_manip "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/type_manipulation"
click node_n_utility "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/utility"
click node_n_functional "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/functional"
click node_n_iterator "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/iterator"
click node_n_memory "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/memory"
click node_n_base_types "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base"
click node_n_safe_ptrs "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/pointer"
click node_n_result_optional "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/result"
click node_n_containers "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/inline_container"
click node_n_strings "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/strings"
click node_n_math_units "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/math"
click node_n_span_mdspan "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/span"
click node_n_sync_os "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/filesystem"
click node_n_testing_base "https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/testing"
click node_n_docs "https://github.com/woven-by-toyota/arene-base/tree/main/docs"
click node_n_stdlib "https://github.com/woven-by-toyota/arene-base/tree/main/stdlib"
click node_n_testlibs "https://github.com/woven-by-toyota/arene-base/tree/main/testlibs"

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_n_build_rules,node_n_build_configs,node_n_build_extensions toneBlue
class node_n_compiler_support,node_n_type_traits,node_n_type_manip,node_n_utility,node_n_functional,node_n_iterator,node_n_memory toneAmber
class node_n_arene_base,node_n_base_types,node_n_safe_ptrs,node_n_result_optional,node_n_containers,node_n_strings,node_n_math_units,node_n_span_mdspan toneMint
class node_n_sync_os toneRose
class node_n_testing_base,node_n_docs,node_n_testlibs toneIndigo
class node_n_stdlib toneTeal
```

## Components

### Build & Config

Bazel rules, variants, and platform selection.

- [rules](https://github.com/woven-by-toyota/arene-base/tree/main/rules): bazel macros · Custom Bazel rules for libraries, tests, redirects, and transitions. · `rules`
- [configs](https://github.com/woven-by-toyota/arene-base/tree/main/configs): build config · Compiler and platform selection, plus config tests. · `configs`
- [extensions](https://github.com/woven-by-toyota/arene-base/tree/main/extensions): bazel extension · Auxiliary Bazel extension/bootstrap logic. · `extensions`

### Foundation

Lowest-level reusable primitives in arene/base.

- [compiler support](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/compiler_support): portable intrinsics · Compiler/platform queries, annotations, and configuration probes. · `arene/base/compiler_support`
- [type traits](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/type_traits): template meta · Trait utilities that underpin most template-heavy code. · `arene/base/type_traits`
- [type manipulation](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/type_manipulation): template meta · Type transformation helpers and compile-time utilities. · `arene/base/type_manipulation`
- [utility](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/utility): core helpers · General-purpose helpers such as swap, in_place, and alignment. · `arene/base/utility`
- [functional](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/functional): call wrappers · Invocation adapters, binders, and function-ref style utilities. · `arene/base/functional`
- [iterator](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/iterator): iterator utilities · Iterator operations and reverse-iterator support. · `arene/base/iterator`
- [memory](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/memory): object lifetime · Construction and destruction primitives for raw storage. · `arene/base/memory`

### Core Facilities

Higher-level reusable libraries built from the foundation.

- [arene/base](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base): core library stack · Primary reusable C++14 library boundary for safety-critical code. · `arene/base`
- [core types](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base): safe primitives · Byte, bit, compare, constraints, contracts, source location, and versioning. · `arene/base`
- [safe pointers](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/pointer): pointer wrappers · Non-null and non-owning pointer abstractions. · `arene/base/pointer`
- [result & optional](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/result): sum types · Error/value and maybe-value abstractions with exception-aware variants. · `arene/base/result`
- [containers](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/inline_container): fixed-capacity containers · Inline/container-like types such as array, vector, map, set, and function. · `arene/base/inline_container`
- [strings](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/strings): string facilities · String views, inline strings, algorithms, and UTF validation. · `arene/base/strings`
- [math & units](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/math): numeric facilities · Math helpers, linear algebra traits, and units/quantity types. · `arene/base/math`
- [span & mdspan](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/span): view types · Non-owning contiguous and multidimensional views. · `arene/base/span`

### Runtime & OS

Stateful, platform-facing components with .cpp implementations.

- [sync & OS](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/filesystem): runtime integration · Mutexes, synchronization primitives, filesystem handles, and temp-directory helpers. · `arene/base/filesystem`

### Testing & Docs

Repository-wide test support, documentation, and examples.

- [testing](https://github.com/woven-by-toyota/arene-base/tree/main/arene/base/testing): test support · Reusable testing utilities, property testing, and gtest adapters. · `arene/base/testing`
- [docs](https://github.com/woven-by-toyota/arene-base/tree/main/docs): user docs · Generated/packageable docs, examples, and architecture diagrams. · `docs`
- [testlibs](https://github.com/woven-by-toyota/arene-base/tree/main/testlibs): test fixtures · Reusable minitest, dummy gtest/gmock, and support utilities. · `testlibs`

### Stdlib Layer

Alternative standard library implementation/shim.

- [stdlib](https://github.com/woven-by-toyota/arene-base/tree/main/stdlib): stdlib shim · Cut-down standard library implementation used as an alternative backend. · `stdlib`

## Connections

- arene/base → compiler support: depends on · Build and implementation feature detection.
- arene/base → type traits: depends on · Template meta-programming foundation.
- arene/base → type manipulation: depends on · Compile-time type transformations.
- arene/base → utility: depends on · General-purpose low-level helpers.
- arene/base → functional: depends on · Callable composition and wrappers.
- arene/base → iterator: depends on · Iterator algorithms and traversal helpers.
- arene/base → memory: depends on · Object lifetime and storage management.
- arene/base → core types: contains · Core safe primitives and boundary types.
- core types → safe pointers: includes · Pointer safety wrappers are part of the core boundary.
- core types → result & optional: includes · Maybe-value and error-value abstractions.
- core types → containers: supports · Container types are built on foundational primitives.
- core types → strings: supports · String facilities layer on core helpers.
- core types → math & units: supports · Numeric and units abstractions.
- core types → span & mdspan: supports · View types and extent handling.
- core types → sync & OS: supports · OS-facing primitives share the same base library boundary.
- containers → result & optional: uses · Variant/optional/result-style containers compose shared primitives.
- containers → safe pointers: uses · Container APIs rely on non-null/non-owning pointer types.
- strings → utility: uses · String algorithms reuse generic helpers.
- math & units → type traits: uses · Traits drive unit and numeric type reasoning.
- span & mdspan → iterator: uses · Traversal and access semantics build on iterators.
- sync & OS → compiler support: uses · Platform branching and runtime configuration.
- testing → testlibs: uses · Shared test harnesses and dummy test frameworks.
- docs → arene/base: documents · Docs and examples describe the library surface.
- docs → stdlib: documents · User docs cover stdlib selection and backend choice.
- rules → arene/base: builds · Bazel macros assemble the library targets.
- configs → rules: configures · Compiler/platform transitions shape target variants.
- extensions → rules: extends · Bootstrap and extension logic supports Bazel integration.
- stdlib → arene/base: backend for · Alternative implementation layer selected at build time.
- stdlib → compiler support: mirrors · Provides stdlib-side support headers and details.
- testing → arene/base: tests · Repository tests validate the library stack.
