Archetype: Modern C++ Native Systems and Algorithms

Target Domain: High-performance compute, geometric modeling, vision processing, low-level protocol engines, and native libraries with C# and Python interop.

---

Technology Stack

Layer	Technology	Rationale and Convention
Language Standard	Modern C++20 / C++23	Concepts, ranges, std::span, std::string_view, and std::expected.
Build System	MSBuild (.vcxproj) & CMake	Visual Studio MSBuild for Windows; CMake for cross-platform and Linux targets.
Package Manager	vcpkg	Manifest mode (vcpkg.json) for deterministic multi-platform dependencies.
Memory Safety	Strict RAII & Smart Pointers	std::unique_ptr and std::shared_ptr. Zero naked new/delete or raw owning pointers.
Testing & Profiling	GoogleTest (gtest) + Benchmark	Unit and simulation suites; Google Benchmark for algorithmic performance profiling.
Sanitizers & Diagnostics	ASan (-fsanitize=address) & UBSan	Automated memory safety and undefined behavior detection in CI.
Interoperability	extern "C" / pybind11	C-style exports for C# [LibraryImport] P/Invoke and pybind11 for Python extensions.

---

Directory Structure

MyNativeLib/
├── vcpkg.json
├── CMakeLists.txt
├── CMakePresets.json
├── README.md
├── ARCHITECTURE.md
├── include/
│   └── my_native_lib/
│       ├── api.h                 # Exported C-ABI symbols
│       ├── algorithm_engine.hpp  # High-level C++ classes
│       └── types.hpp
├── src/
│   ├── algorithm_engine.cpp
│   ├── interop_exports.cpp       # extern "C" wrappers
│   └── diagnostic_taps.cpp       # Ring buffer state dumps
└── tests/
    ├── CMakeLists.txt
    ├── test_algorithms.cpp       # GoogleTest assertions
    ├── test_harness_stress.cpp   # High-volume closed-loop simulation
    └── benchmark_algorithms.cpp  # Google Benchmark suites

---

C-ABI Interop Pattern for CSharp and Python

C++ Export Header

Expose a clean C-ABI boundary (extern "C") so managed runtimes can invoke native algorithms without C++ name-mangling or exception-boundary issues:

// include/my_native_lib/api.h
#pragma once

#if defined(_WIN32)
  #define EXPORT_API __declspec(dllexport)
#else
  #define EXPORT_API __attribute__((visibility("default")))
#endif

extern "C" {
    EXPORT_API int ProcessDataBatch(
        const double* inputData, 
        int length, 
        double* outputData, 
        char* errorBuffer, 
        int errorBufferSize
    );
}

C# LibraryImport Binding

Consume the exported C-ABI symbols in .NET 10 using source-generated [LibraryImport] and zero-allocation Span<T> buffers:

// C# .NET 10 Consumption via [LibraryImport]
using System.Runtime.InteropServices;

public static partial class NativeInterop
{
    [LibraryImport("MyNativeLib", StringMarshalling = StringMarshalling.Utf8)]
    public static partial int ProcessDataBatch(
        ReadOnlySpan<double> inputData,
        int length,
        Span<double> outputData,
        Span<byte> errorBuffer,
        int errorBufferSize
    );
}

---

Representative Test Harness: Parameter Sweeps

Boundary and Disturbance Sweeps

Verify numerical algorithms and solvers using parameterized GoogleTest suites (TEST_P; see C++ Native Algorithms Harness Recipes):

• Sweep parameter spaces across boundary values (-1e5, -1.0, 0.0, 1.0, 1e5) and learning rate combinations.
• Never mock mathematical algorithms, numerical convergence routines, or hardware state machines.
• Execute all test suites under AddressSanitizer (ASan) and UndefinedBehaviorSanitizer (UBSan).
• Assert convergence flags, residual error tolerances, and iteration limits.

GoogleTest Parameterized Suite

#include <gtest/gtest.h>
#include "numerical_solver.hpp"

class SolverBoundaryTest : public ::testing::TestWithParam<std::tuple<double, double, int>> {};

TEST_P(SolverBoundaryTest, ConvergesWithinToleranceUnderDisturbance) {
    auto [initial_value, learning_rate, max_iterations] = GetParam();
    
    SolverConfig config{.lr = learning_rate, .max_iter = max_iterations};
    NumericalSolver solver(config);

    auto result = solver.Solve(initial_value);

    EXPECT_TRUE(result.converged);
    EXPECT_LT(std::abs(result.residual), 1e-6);
    EXPECT_LE(result.iterations_taken, max_iterations);
}

INSTANTIATE_TEST_SUITE_P(
    BoundarySweeps,
    SolverBoundaryTest,
    ::testing::Combine(
        ::testing::Values(-1e5, -1.0, 0.0, 1.0, 1e5),
        ::testing::Values(0.001, 0.01, 0.1),
        ::testing::Values(10, 100, 1000)
    )
);