# compaile/ctrack architecture

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

- Interactive diagram: https://gitdiagram.com/compaile/ctrack
- Repository: https://github.com/compaile/ctrack

## Overview

##### Project Type and Purpose
- CTRACK is a header-only, performance tracking/benchmarking library designed to instrument C++ functions with minimal overhead.
- Its primary purpose is to log function call performance metrics (like execution times, thread usage, and statistical details) in both development and production environments.
- It uses macros such as CTRACK, CTRACK_DEV, and CTRACK_PROD to enable performance tracking in the user’s code.
- The library can be integrated directly via a single header inclusion or as a CMake package, and it prints detailed tables (Summary and Detail) for performance insights.

##### File Structure
- The top-level items include configuration files (CMakeLists.txt, .gitignore, Config.cmake.in), license, and README.
- The cmake directory contains additional build configuration files.
- The “include” directory holds the core header file (ctrack.hpp) which is the heart of the library.
- The “examples” directory shows different sample usage scenarios (e.g., basic singlethreaded, complex multithreaded, prime counter, etc.) indicating the library’s versatility in handling both single- and multi-threaded contexts.
- The build and installation process is managed by CMake scripts, showing an intention for integration ease with existing C++ projects.

##### Main Components
a. Developer Application Code:
- Users’ application code that integrates CTRACK via #include "ctrack.hpp" and uses the provided macros.
b. Core Tracking Module:
- The single header (ctrack.hpp) that implements:
- Macros (CTRACK, CTRACK_DEV, CTRACK_PROD) used for function instrumentation.
- Mechanisms for event recording and data management.
- Calculation functions for generating statistical summaries, such as the Summary Table and Detail Table.
c. Result Processing Subsystem:
- Components that convert raw tracking data into human-readable output, showcasing metrics like min, mean, median, max, and additional statistical properties (standard deviation, coefficient of variation).
d. Build and Integration Layer:
- The CMake build system which handles package configuration, installation (via CMakeLists.txt and auxiliary cmake scripts), and optional integration with TBB for parallel computation in metric calculations.

##### Relationships and Data Flow
- When the developer’s function is instrumented (by placing a CTRACK macro at the beginning of a function), control flows from the user’s function to the tracking module inside ctrack.hpp.
- The tracking module records performance events and stores them, including timing and thread information.
- Upon completion of specific phases or on demand, the result processing functions (result_print or result_as_string) are called to compute and output statistical summaries and detailed data.
- The build system (CMake) ensures that the core library and its dependencies (e.g., optional TBB) are correctly configured for use within an application.

##### Architectural Patterns and Design Principles
- Header-only Library: Simplifies integration by requiring only a single file inclusion.
- Minimal Overhead & Runtime Efficiency: The design ensures that tracking incurs very low overhead to not interfere with performance-critical code.
- Configurability: The usage of macros and runtime settings (e.g., ctrack_result_settings) allows flexible configuration based on the environment.
- Separation of Concerns: Differentiates between tracking (data collection), result processing (aggregation and formatting), and external integration (via CMake).

- Each component should be clearly labeled with its name and purpose.
- The header-only tracking library (ctrack.hpp),
- Build/integration layer (CMake and related scripts),
- Optional dependencies (like TBB),
- And the user application code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Flow
    A["Developer Application Code\n(Uses CTRACK macros)"]:::frontend
    B["CTRACK Tracking Engine\n(ctrack.hpp)"]:::core
    C["Result Processing\n(Statistics & Output Formatting)"]:::core

    A -->|"instruments"| B
    B -->|"records_events"| C

    %% Build and Integration Layer Subgraph
    subgraph "Build and Integration Layer"
        BS1["CMakeLists.txt"]:::integration
        BS2["Config.cmake.in"]:::integration
        BS3["cmake/ Scripts"]:::integration
    end

    %% Optional Dependency
    TBB["Optional TBB Dependency"]:::integration

    %% Build system integrates into the tracking engine
    BS1 -->|"configures"| B
    BS2 -->|"configures"| B
    BS3 -->|"configures"| B
    TBB -->|"optional_parallel"| B

    %% Click Events
    click A "https://github.com/compaile/ctrack/tree/main/examples/"
    click B "https://github.com/compaile/ctrack/blob/main/include/ctrack.hpp"
    click C "https://github.com/compaile/ctrack/blob/main/include/ctrack.hpp"
    click BS1 "https://github.com/compaile/ctrack/blob/main/CMakeLists.txt"
    click BS2 "https://github.com/compaile/ctrack/blob/main/Config.cmake.in"
    click BS3 "https://github.com/compaile/ctrack/tree/main/cmake/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFFACD,stroke:#000,stroke-width:2px;
```
