# lectem/cpp-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/lectem/cpp-boilerplate
- Repository: https://github.com/lectem/cpp-boilerplate

## Overview

##### Project type and purpose
- This is a C++ “modern CMake” boilerplate/template project. It isn’t an end-user application but a reusable foundation that showcases a “best-practice” build setup using CMake 3.x, common C++ libraries (fmt, spdlog), unit testing (doctest), and CI/CD integration.

##### File structure
- Top‐level folders:
- cmake/           → custom CMake scripts (warnings, LTO, coverage, DLL fixups, CI helpers)
- external/        → submodules for fmt, spdlog, doctest
- /         → public headers (foo.h)
- source/          → implementation files and main.cpp
- tests/           → unit tests (failtest.cpp, successtest.cpp)
- .github/workflows → GitHub Actions workflows
- Key files: CMakeLists.txt (entry point for build), CreateBoilerPlate.sh (bootstrapping), appveyor.yml, CodeQL config, .clang-format.

##### README for additional insights
- Purpose: teach/boot- strap new CMake projects, illustrate modern CMake patterns, CI integration (GitHub Actions, AppVeyor, Codecov, CDash).
- Dependencies: C++14, Git (for submodules), external libs (fmt, spdlog, doctest).

##### Main components
a. Code Base
- Source Module: include/ + source/ → produces library or executable (foo library + main)
- Test Module: tests/ → linked against library, uses doctest
b. Build System
- CMake Core (CMakeLists.txt)
- Custom CMake Scripts (cmake/*.cmake)
- External Submodules (external/{fmt,spdlog,doctest})
c. CI/CD Infrastructure
- GitHub Actions workflow (.github/workflows/cmake.yml)
- AppVeyor (appveyor.yml)
- CodeQL (code scanning)
- Codecov & CDash (coverage & test dashboards)
d. Developer Workflow
- Developer clones repo → runs CreateBoilerPlate.sh → edits CMakeLists + code → commits → CI pipelines execute

##### Relationships and data flows
- Developer pushes code to GitHub → triggers GitHub Actions & CodeQL
- Build System (CMake) configures & generates native build files → compilers compile code + link external libs → binaries produced
- CTest runs unit tests via doctest → test results sent to CDash
- Coverage instrumentation (Coverage.cmake) → coverage reports sent to Codecov
- On Windows builds: CopyDllsForDebug.cmake copies DLLs for runtime

##### Architectural patterns and design principles
- Single orchestrator (CMake) managing multi‐platform builds
- Submodules for small dependencies (fmt, spdlog, doctest) to simplify bootstrapping
- Modular CMake scripts for cross-project reuse (warnings, LTO, coverage)
- Clear separation between code, tests, build logic, and CI configuration

##### Detail
- Every top‐level folder or script that plays a role in the build or CI pipeline.
- Platform-specific behavior (windows-only.cpp + CopyDllsForDebug.cmake).
- Both local (developer workstation) and remote (GitHub, AppVeyor, Codecov) stages.

1) the modular CMake-driven build architecture,
2) how external libraries are included,
3) where tests and coverage fit in, and
4) how CI/CD orchestrates the entire lifecycle of this boilerplate project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    Developer["Developer"]:::actor
    BootScript["CreateBoilerPlate.sh"]:::script
    click BootScript "https://github.com/lectem/cpp-boilerplate/blob/master/CreateBoilerPlate.sh"
    Developer -->|"clone & run script"| BootScript

    %% Code Base
    subgraph "Code Base"
        include["include/"]:::code
        click include "https://github.com/lectem/cpp-boilerplate/blob/master/include/foo.h"
        source["source/"]:::code
        click source "https://github.com/lectem/cpp-boilerplate/blob/master/source/main.cpp"
        tests["tests/"]:::code
        click tests "https://github.com/lectem/cpp-boilerplate/blob/master/tests/CMakeLists.txt"
    end
    BootScript --> include
    BootScript --> source
    BootScript --> tests

    %% Build System
    subgraph "Build System"
        CMakeCore["CMake Core\nCMakeLists.txt\nCTestConfig.cmake"]:::build
        click CMakeCore "https://github.com/lectem/cpp-boilerplate/blob/master/CMakeLists.txt"
        subgraph "Custom CMake Scripts"
            BoilerPlateConfig["BoilerPlateConfig.cmake.in"]:::build
            click BoilerPlateConfig "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/BoilerPlateConfig.cmake.in"
            CICTest["CI.CTestScript.cmake"]:::build
            click CICTest "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/CI.CTestScript.cmake"
            CTestCustom["CTestCustom.cmake.in"]:::build
            click CTestCustom "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/CTestCustom.cmake.in"
            CopyDlls["CopyDllsForDebug.cmake"]:::build
            click CopyDlls "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/CopyDllsForDebug.cmake"
            CoverageScript["Coverage.cmake"]:::build
            click CoverageScript "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/Coverage.cmake"
            LTO["LTO.cmake"]:::build
            click LTO "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/LTO.cmake"
            Warnings["Warnings.cmake"]:::build
            click Warnings "https://github.com/lectem/cpp-boilerplate/blob/master/cmake/Warnings.cmake"
        end
    end

    %% External Dependencies
    subgraph "External Submodules"
        fmt["fmt"]:::external
        click fmt "https://github.com/lectem/cpp-boilerplate/tree/master/external/fmt/"
        spdlog["spdlog"]:::external
        click spdlog "https://github.com/lectem/cpp-boilerplate/tree/master/external/spdlog/"
        doctest["doctest"]:::external
        click doctest "https://github.com/lectem/cpp-boilerplate/tree/master/external/doctest/"
    end

    %% CI/CD Services
    subgraph "CI/CD"
        GitHub["GitHub Repo"]:::service
        subgraph "GitHub Actions"
            GHA1["cmake.yml"]:::service
            click GHA1 "https://github.com/lectem/cpp-boilerplate/blob/master/.github/workflows/cmake.yml"
            GHA2["codeql.yml"]:::service
            click GHA2 "https://github.com/lectem/cpp-boilerplate/blob/master/.github/workflows/codeql.yml"
        end
        AppVeyor["AppVeyor"]:::service
        click AppVeyor "https://github.com/lectem/cpp-boilerplate/blob/master/appveyor.yml"
        CodeQL["CodeQL Scanning"]:::service
        Codecov["Codecov"]:::service
        CDash["CDash"]:::service
    end

    %% Workflow
    Developer -->|"push code"| GitHub
    GitHub -->|trigger| GHA1
    GitHub -->|trigger| GHA2
    GitHub -->|trigger| AppVeyor
    GitHub -->|trigger| CodeQL

    GHA1 -->|"invoke configure"| CMakeCore
    GHA1 -->|"load scripts"| BoilerPlateConfig
    GHA1 --> CITest["Run CTest"]:::exec
    CMakeCore -->|"import submodules"| fmt
    CMakeCore --> spdlog
    CMakeCore --> doctest
    CMakeCore -->|"generate build files"| Compiler["Compiler"]:::exec
    Compiler -->|"compile & link"| Artifacts["Artifacts\n(library & binary)"]:::artifact
    Artifacts -->|"run tests"| CITest
    CITest -->|"upload results"| CDash
    CMakeCore -->|"instrument coverage"| CoverageScript
    CoverageScript -->|"send report"| Codecov
    CMakeCore --> CopyDlls

    AppVeyor --> CMakeCore
    CodeQL -->|"scan code"| GitHub

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef code fill:#bbf,stroke:#333,stroke-width:1px
    classDef build fill:#9f9,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef service fill:#b9f,stroke:#333,stroke-width:1px
    classDef exec fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef artifact fill:#fcf,stroke:#933,stroke-width:1px
```
