# andreasfertig/cppinsights architecture

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

- Interactive diagram: https://gitdiagram.com/andreasfertig/cppinsights
- Repository: https://github.com/andreasfertig/cppinsights

## Overview

##### Project Type & Purpose
- This is an open-source, command-line tool (“C++ Insights”) that uses Clang’s AST to perform a source-to-source transformation of C++ code (revealing compiler-injected constructs).
- It is not a web app or microservices system but a single binary built on modular C++ libraries, with extensive test suites, documentation generators, and deployment scripts.

##### Top-Level Components
a. CLI Frontend
- Entry point (main from CodeGenerator.cpp/ASTHelpers.cpp).
- Argument parsing (via LLVM/Clang command-line infrastructure).
- Dispatch to core engine.
b. Core Engine
- AST Helpers (ASTHelpers.*) – utilities to traverse/manipulate Clang AST.
- Insights Options & Static Strings (Insights*.h/.cpp) – centralized configuration, feature toggles.
- Lifetime/Number/Stack utilities (LifetimeTracker.cpp, NumberIterator.h, StackList.h).
c. Transformation Modules
- CfrontCodeGenerator.cpp – handles old-style conversion.
- CoroutinesCodeGenerator.cpp – coroutine lowering.
- CodeGenerator.* (and types) – orchestrates per-construct generators.
- OutputFormatHelper.* – formats the transformed AST back to C++ source.
d. Infrastructure & Utilities
- DPrint (debug/logging).
- Read/write configuration (InsightsOptions.def).
- Scripts (scripts/*.sh/.py) – CI checks, release, include path discovery, bash completion.
- CMakeLists.txt – build orchestration, external project integration.
e. External Dependencies
- Clang / LLVM libraries (libclangAST, libLLVM).
- Python (for docs post-processing).
- Bash (for shell scripts).
f. Documentation & Examples
- docs/ – Doxygen config, markdown guides, example transformations, OptionDocumentationGenerator.
- artwork/logo, style.css, header/footer for HTML.
g. Testing Harness
- tests/ – hundreds of feature tests, shell scripts (testSTDIN.sh, runTest.py), expected outputs.
- GitHub Actions workflow (ci.yml) for build, test, coverage (codecov).

##### Relationships & Data Flow
1) User invokes `insights <file> [-- options]` → CLI Frontend parses arguments.
2) CLI Frontend feeds the file and flags into the Core Engine.
3) Core Engine uses Clang AST to parse input, then hands over AST nodes to Transformation Modules.
4) Each Transformation Module applies specific source-to-source rules, building an internal representation of rewritten code.
5) OutputFormatHelper serializes the internal representation back to valid C++ code.
6) CLI Frontend writes the output to stdout or file.
7) Tests invoke the binary, capture stdout, compare against expected files.
8) Documentation generators scan InsightsOptions and examples to produce human-readable docs.

##### Architectural Patterns & Principles
- Modular design: each language feature transformation is a separate code generator plugin.
- Separation of concerns: parsing (Clang), transformation (Insights modules), formatting (OutputFormatHelper).
- Build-time extensibility: CMake plugins allow integration inside or outside LLVM projects.
- Extensive automation: CI/CD scripts for formatting, linting, coverage.

##### Technologies & Frameworks
- C++17 (with optional C++20 support flags)
- Clang/LLVM libraries
- CMake (with Ninja or Visual Studio generators)
- Python (docs post-processing, getinclude.py)
- Bash (autocomplete, CI scripts)
- Doxygen (API and option docs)
- GitHub Actions for CI

##### Final Recommendation
- Overlay CI/CD pipeline alongside: GitHub Actions → codecov.
- Extensibility points (e.g., how to add a new generator).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User invocation
    User["User<br/>(CLI Invocation)"]:::external

    %% CLI Frontend
    subgraph "CLI Frontend" 
        direction TB
        CGCPP["CodeGenerator.cpp"]:::cli
        CGH["CodeGenerator.h"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        subgraph "AST Helpers"
            ASTCPP["ASTHelpers.cpp"]:::core
            ASTH["ASTHelpers.h"]:::core
        end
        subgraph "Insights Options & Strings"
            IODEF["InsightsOptions.def"]:::core
            ISS["InsightsStaticStrings.h"]:::core
        end
        subgraph "Utilities & Types"
            INSCPP["Insights.cpp"]:::core
            INSH["Insights.h"]:::core
            IHCPP["InsightsHelpers.cpp"]:::core
            IHH["InsightsHelpers.h"]:::core
            IONCE["InsightsOnce.h"]:::core
            ISCAT["InsightsStrCat.h"]:::core
            IST["InsightsStrongTypes.h"]:::core
            IUTIL["InsightsUtility.h"]:::core
        end
        subgraph "Lifetime/Number/Stack"
            LTRK["LifetimeTracker.cpp"]:::core
            NIT["NumberIterator.h"]:::core
            SLIST["StackList.h"]:::core
        end
    end

    %% Transformation Modules
    subgraph "Transformation Modules"
        direction TB
        CFCG["CfrontCodeGenerator.cpp"]:::transform
        CORO["CoroutinesCodeGenerator.cpp"]:::transform
        CGTYPES["CodeGeneratorTypes.h"]:::transform
    end

    %% Output Formatter
    subgraph "Output Formatter"
        direction TB
        OFFCPP["OutputFormatHelper.cpp"]:::formatter
        OFFH["OutputFormatHelper.h"]:::formatter
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        DPRINTCPP["DPrint.cpp"]:::infra
        DPRINTH["DPrint.h"]:::infra
        CMAKE["CMakeLists.txt"]:::infra
        SCRIPTS["scripts/"]:::infra
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        CLANG["libclangAST"]:::externalDep
        LLVM["libLLVM"]:::externalDep
        PYTHON["Python"]:::externalDep
        BASH["Bash"]:::externalDep
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        direction TB
        DOCP["docs/"]:::docs
    end

    %% Testing Harness
    subgraph "Testing Harness"
        direction TB
        TESTS["tests/"]:::test
        RUNPY["tests/runTest.py"]:::test
        TSTSH["tests/testSTDIN.sh"]:::test
        CIYML[".github/workflows/ci.yml"]:::test
    end

    %% Flow arrows
    User -->|"invoke insights"| CGCPP
    CGCPP -->|"parses args"| CGCPP
    CGCPP -->|"dispatch"| ASTCPP
    ASTCPP -->|AST nodes| CFCG
    ASTCPP -->|AST nodes| CORO
    CFCG -->|"transformed IR"| OFFCPP
    CORO -->|"transformed IR"| OFFCPP
    OFFCPP -->|"format code"| CGCPP
    CGCPP -->|"stdout/file"| User

    %% Tests flow
    TESTS -->|run binary| User

    %% Docs generation
    IODEF -->|scan options| DOCP

    %% CI pipeline
    CIYML -->|runs tests & coverage| TESTS

    %% Click events
    click CGCPP "https://github.com/andreasfertig/cppinsights/blob/main/CodeGenerator.cpp"
    click CGH "https://github.com/andreasfertig/cppinsights/blob/main/CodeGenerator.h"
    click ASTCPP "https://github.com/andreasfertig/cppinsights/blob/main/ASTHelpers.cpp"
    click ASTH "https://github.com/andreasfertig/cppinsights/blob/main/ASTHelpers.h"
    click IODEF "https://github.com/andreasfertig/cppinsights/blob/main/InsightsOptions.def"
    click ISS "https://github.com/andreasfertig/cppinsights/blob/main/InsightsStaticStrings.h"
    click INSCPP "https://github.com/andreasfertig/cppinsights/blob/main/Insights.cpp"
    click INSH "https://github.com/andreasfertig/cppinsights/blob/main/Insights.h"
    click IHCPP "https://github.com/andreasfertig/cppinsights/blob/main/InsightsHelpers.cpp"
    click IHH "https://github.com/andreasfertig/cppinsights/blob/main/InsightsHelpers.h"
    click IONCE "https://github.com/andreasfertig/cppinsights/blob/main/InsightsOnce.h"
    click ISCAT "https://github.com/andreasfertig/cppinsights/blob/main/InsightsStrCat.h"
    click IST "https://github.com/andreasfertig/cppinsights/blob/main/InsightsStrongTypes.h"
    click IUTIL "https://github.com/andreasfertig/cppinsights/blob/main/InsightsUtility.h"
    click LTRK "https://github.com/andreasfertig/cppinsights/blob/main/LifetimeTracker.cpp"
    click NIT "https://github.com/andreasfertig/cppinsights/blob/main/NumberIterator.h"
    click SLIST "https://github.com/andreasfertig/cppinsights/blob/main/StackList.h"
    click CFCG "https://github.com/andreasfertig/cppinsights/blob/main/CfrontCodeGenerator.cpp"
    click CORO "https://github.com/andreasfertig/cppinsights/blob/main/CoroutinesCodeGenerator.cpp"
    click CGTYPES "https://github.com/andreasfertig/cppinsights/blob/main/CodeGeneratorTypes.h"
    click OFFCPP "https://github.com/andreasfertig/cppinsights/blob/main/OutputFormatHelper.cpp"
    click OFFH "https://github.com/andreasfertig/cppinsights/blob/main/OutputFormatHelper.h"
    click DPRINTCPP "https://github.com/andreasfertig/cppinsights/blob/main/DPrint.cpp"
    click DPRINTH "https://github.com/andreasfertig/cppinsights/blob/main/DPrint.h"
    click CMAKE "https://github.com/andreasfertig/cppinsights/blob/main/CMakeLists.txt"
    click SCRIPTS "https://github.com/andreasfertig/cppinsights/tree/main/scripts/"
    click DOCP "https://github.com/andreasfertig/cppinsights/tree/main/docs/"
    click TESTS "https://github.com/andreasfertig/cppinsights/tree/main/tests/"
    click RUNPY "https://github.com/andreasfertig/cppinsights/blob/main/tests/runTest.py"
    click TSTSH "https://github.com/andreasfertig/cppinsights/blob/main/tests/testSTDIN.sh"
    click CIYML "https://github.com/andreasfertig/cppinsights/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef cli fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef core fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef transform fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef formatter fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef infra fill:#fffde7,stroke:#f9a825,stroke-width:2px;
    classDef externalDep fill:#eeeeee,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5;
    classDef docs fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef test fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef external fill:#ffffff,stroke:#000000,stroke-width:1px,stroke-dasharray: 3 3;
```
