# catchorg/catch2 architecture

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

- Interactive diagram: https://gitdiagram.com/catchorg/catch2
- Repository: https://github.com/catchorg/catch2

## Overview

##### Main components
- Library Source Modules
– Core “catch2” functionality
- interfaces
- internal
- matchers
- reporters
- generators
- benchmark
– Third-party integration (e.g. clara.hpp)
- Build & Packaging
– Bazel (BUILD.bazel, MODULE.bazel)
– CMake (CMakeLists.txt, presets, catch2-*.cmake)
– Meson (meson.build, meson_options.txt)
– Conan (conanfile.py, .conan/*)
- Testing Suites
– SelfTest (introspective, usage, timing, misc)
– ExtraTests
– Fuzzing (fuzz_* in fuzzing/)
– TestScripts (Python/C++ helpers under tests/TestScripts)
- Examples
– sample .cpp files in examples/
- Documentation
– docs/ (tutorial, reference, FAQs, guides)
– Doxyfile
- Tooling & Scripts
– tools/scripts (CI helpers, release scripts, snippet extractors)
– tools/misc (coverage helpers, appveyor scripts)
- CI / External Services
– GitHub Actions workflows (.github/workflows/*.yml)
– AppVeyor (appveyor.yml)
– Codecov, Shields badges
– Discord/chat (link)

##### Relationships & data flows
- Source Modules → Build & Packaging
– The build system (Bazel/CMake/Meson/Conan) compiles core modules into static/shared libraries or single-header amalgamations.
- Build → Testing Suites
– Built library is linked into SelfTest, ExtraTests, Fuzzing executables.
- Build → Examples
– Examples are compiled against the Catch2 library to demonstrate usage.
- Build → Documentation
– Doxygen scans headers to generate API docs; docs snippets updated via tools/scripts.
- CI Workflows → Build & Test → Codecov
– GitHub Actions & AppVeyor invoke build scripts; on success tests run; coverage uploaded to Codecov.
- Tooling → Release Process
– scripts under tools/scripts implement release version bump, snippet extraction, amalgamated file generation.

##### Architectural patterns & design principles
- Modularity
– Each subfolder (interfaces, internal, matchers, reporters, etc.) is a cohesive component with well-defined responsibilities.
- Multi-build support
– Abstract build logic to support multiple systems, enabling consumers to integrate Catch2 into various C++ ecosystems.
- Single-header vs multi-header options
– Amalgamated header generation (extras/) vs standard multi-header library.
- Extensibility points
– Reporter plugin interfaces, generator adapters, listener hooks, custom assertion macros.
- Decoupled testing
– Tests are structured to self-validate, introspect library internals, and fuzz specific subsystems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Modules
    subgraph "Source Modules" 
        interfaces["interfaces"]:::source
        internal["internal"]:::source
        matchers["matchers"]:::source
        reporters["reporters"]:::source
        generators["generators"]:::source
        benchmark["benchmark"]:::source
        clara["clara (third_party)"]:::source
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        bazel["Bazel"]:::build
        cmake["CMake"]:::build
        meson["Meson"]:::build
        conan["Conan"]:::build
    end

    %% Central Library Output
    catchlib["Catch2 Library\n(static/shared/amalgamation)"]:::output

    %% Testing Suites
    subgraph "Testing Suites"
        selftest["SelfTest"]:::test
        extratest["ExtraTests"]:::test
        fuzzing["Fuzzing"]:::test
        testscripts["TestScripts"]:::test
    end

    %% Examples & Documentation
    examples["Examples"]:::doc
    docs["Documentation"]:::doc

    %% Tooling & Scripts
    tools_scripts["tools/scripts"]:::tool
    tools_misc["tools/misc"]:::tool

    %% CI / External Services
    gha["GitHub Actions"]:::ci
    appveyor["AppVeyor"]:::ci
    codecov["Codecov"]:::ext
    discord["Discord/Chat"]:::ext

    %% Relationships
    interfaces --> bazel
    internal --> bazel
    matchers --> bazel
    reporters --> bazel
    generators --> bazel
    benchmark --> bazel
    clara --> bazel

    interfaces --> cmake
    internal --> cmake
    matchers --> cmake
    reporters --> cmake
    generators --> cmake
    benchmark --> cmake
    clara --> cmake

    interfaces --> meson
    internal --> meson
    matchers --> meson
    reporters --> meson
    generators --> meson
    benchmark --> meson
    clara --> meson

    interfaces --> conan
    internal --> conan
    matchers --> conan
    reporters --> conan
    generators --> conan
    benchmark --> conan
    clara --> conan

    bazel --> catchlib
    cmake --> catchlib
    meson --> catchlib
    conan --> catchlib

    catchlib --> selftest
    catchlib --> extratest
    catchlib --> fuzzing
    catchlib --> testscripts
    catchlib --> examples
    catchlib --> docs

    tools_scripts --> docs

    gha --> bazel
    gha --> cmake
    gha --> meson
    gha --> conan
    gha --> selftest
    gha --> extratest
    gha --> fuzzing
    gha --> testscripts

    appveyor --> cmake
    appveyor --> selftest
    appveyor --> extratest

    selftest --> codecov
    extratest --> codecov
    fuzzing --> codecov
    testscripts --> codecov

    gha --> codecov
    codecov --- discord

    %% Click Events
    click interfaces "https://github.com/catchorg/catch2/tree/devel/src/catch2/interfaces/"
    click internal "https://github.com/catchorg/catch2/tree/devel/src/catch2/internal/"
    click matchers "https://github.com/catchorg/catch2/tree/devel/src/catch2/matchers/"
    click reporters "https://github.com/catchorg/catch2/tree/devel/src/catch2/reporters/"
    click generators "https://github.com/catchorg/catch2/tree/devel/src/catch2/generators/"
    click benchmark "https://github.com/catchorg/catch2/tree/devel/src/catch2/benchmark/"
    click clara "https://github.com/catchorg/catch2/blob/devel/third_party/clara.hpp"
    click bazel "https://github.com/catchorg/catch2/blob/devel/BUILD.bazel"
    click bazel "https://github.com/catchorg/catch2/blob/devel/.bazelrc"
    click cmake "https://github.com/catchorg/catch2/blob/devel/CMakeLists.txt"
    click cmake "https://github.com/catchorg/catch2/tree/devel/CMake/"
    click cmake "https://github.com/catchorg/catch2/blob/devel/CMakePresets.json"
    click meson "https://github.com/catchorg/catch2/blob/devel/meson.build"
    click meson "https://github.com/catchorg/catch2/blob/devel/meson_options.txt"
    click meson "https://github.com/catchorg/catch2/blob/devel/src/catch2/meson.build"
    click conan "https://github.com/catchorg/catch2/blob/devel/conanfile.py"
    click conan "https://github.com/catchorg/catch2/blob/devel/.conan/build.py"
    click conan "https://github.com/catchorg/catch2/tree/devel/.conan/test_package/"
    click selftest "https://github.com/catchorg/catch2/tree/devel/tests/SelfTest/"
    click extratest "https://github.com/catchorg/catch2/tree/devel/tests/ExtraTests/"
    click fuzzing "https://github.com/catchorg/catch2/tree/devel/fuzzing/"
    click testscripts "https://github.com/catchorg/catch2/tree/devel/tests/TestScripts/"
    click examples "https://github.com/catchorg/catch2/tree/devel/examples/"
    click docs "https://github.com/catchorg/catch2/tree/devel/docs/"
    click docs "https://github.com/catchorg/catch2/tree/devel/Doxyfile"
    click tools_scripts "https://github.com/catchorg/catch2/tree/devel/tools/scripts/"
    click tools_misc "https://github.com/catchorg/catch2/tree/devel/tools/misc/"
    click gha "https://github.com/catchorg/catch2/tree/devel/.github/workflows/"
    click appveyor "https://github.com/catchorg/catch2/blob/devel/appveyor.yml"
    click codecov "https://github.com/catchorg/catch2/blob/devel/codecov.yml"

    %% Styles
    classDef source fill:#e0f7fa,stroke:#0288d1,color:#000;
    classDef build fill:#ffe0b2,stroke:#fb8c00,color:#000;
    classDef output fill:#c8e6c9,stroke:#388e3c,color:#000;
    classDef test fill:#f3e5f5,stroke:#8e24aa,color:#000;
    classDef doc fill:#fff9c4,stroke:#fbc02d,color:#000;
    classDef tool fill:#d1c4e9,stroke:#5e35b1,color:#000;
    classDef ci fill:#bbdefb,stroke:#1976d2,color:#000;
    classDef ext fill:#cfd8dc,stroke:#455a64,color:#000;
```
