# getml/reflect-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/getml/reflect-cpp
- Repository: https://github.com/getml/reflect-cpp

## Overview

##### Project Type & Purpose
- This project is a high-performance C++20 library focused on reflection-based serialization, deserialization, and validation. It is similar in spirit to libraries like Python’s pydantic or Rust’s serde.
- It supports multiple serialization formats (JSON, Avro, BSON, Cap’n Proto, CBOR, flexbuffers, msgpack, TOML, UBJSON, XML, YAML) and provides a modular interface that both reduces boilerplate code and enhances code safety.

##### File Structure
- Top-Level Directories:
- Contains the public headers (the core reflection API and various meta-programming utilities) organized into subfolders (e.g., rfl, rfl/avro, rfl/json, etc.).
- src: Contains the source code implementations for the core library and format-specific writers/readers (e.g., reflectcpp_json.cpp, reflectcpp_xml.cpp, etc.).
- tests: Contains extensive test suites for each serialization module (organized subdirectories for avro, bson, capnproto, cbor, json, etc.), emphasizing a rigorous testing approach.
- benchmarks: Contains performance-testing code with examples for different serialization formats.
- docs: Provides documentation with guides, installation instructions, and examples.
- Additionally, configuration files such as CMakeLists.txt, CI/CD workflows (.github folder), and package management files (conanfile.py, vcpkg.json) indicate a well-structured build and integration pipeline.

- Architectural Patterns:
- Modularity: The separation of common reflection infrastructure (in “include” and “src”) from the format-specific modules (each serialization format has its own implementation and tests).
- Extensibility: The design supports adding new serialization formats through well-defined interfaces. This is apparent from the dedicated modules for each format.
- Testing and Benchmarking: A strong emphasis on tests (across many directories) and performance benchmarks – indicating continuous integration and testing practices.

##### Components
a. Core Reflection Engine:
- The heart of the library handling compile-time reflection, field extraction, and reflective programming.
- Located in “include/rfl.hpp” and implemented by various internal modules (src/rfl/internal/…).

b. Serialization Adapters / Format Modules:
- Modules dedicated to different serialization formats: JSON (src/reflectcpp_json.cpp and include/rfl/json/…), Avro, BSON, Cap’n Proto, CBOR, flexbuffers, msgpack, TOML, UBJSON, XML, YAML.
- Each module interfaces with external third-party libraries (for instance, yyjson for JSON, pugixml for XML, etc.).

c. Testing and Benchmarks:
- A testing framework that exercises the serialization and reflective API. Tests are organized per serialization format under “tests/…”.
- Benchmarks (under “benchmarks”) validate performance claims.

d. Build, CI/CD, and Documentation:
- Build and configuration managed largely by CMake (central CMakeLists.txt files) and supported by CI/CD pipelines found under “.github/workflows.”
- Documentation (“docs” folder) and external integration (Conan, vcpkg) indicate how users incorporate the library.

e. External Dependencies:
- Third-party libraries (e.g., yyjson, pugixml, toml11, msgpack-c) are used as backends for specific serialization formats.

##### Relationships and Interactions
- The testing suite accesses both the core and the adapters to validate functionality and performance.
- CI/CD and build configurations sit at the periphery, interacting with all modules to ensure continuous integration and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Code
    U["User Code"]:::user
    U -->|"sends data"| Core["Core Reflection Engine"]:::core

    %% Core Reflection Engine and its Click Events attached below

    %% Serialization Adapters Subgraph
    subgraph "Serialization Adapters"
        JSONAdapter["JSON Adapter"]:::adapter
        AvroAdapter["Avro Adapter"]:::adapter
        BSONAdapter["BSON Adapter"]:::adapter
        CapnProtoAdapter["Cap'n Proto Adapter"]:::adapter
        CBORAdapter["CBOR Adapter"]:::adapter
        FlexAdapter["Flexbuffers Adapter"]:::adapter
        MsgpackAdapter["Msgpack Adapter"]:::adapter
        TOMLAdapter["TOML Adapter"]:::adapter
        UBJSONArrayAdapter["UBJSON Adapter"]:::adapter
        XMLAdapter["XML Adapter"]:::adapter
        YAMLAdapter["YAML Adapter"]:::adapter
    end

    %% Link Core Reflection Engine with each Adapter
    Core -->|"translates"| JSONAdapter
    Core -->|"translates"| AvroAdapter
    Core -->|"translates"| BSONAdapter
    Core -->|"translates"| CapnProtoAdapter
    Core -->|"translates"| CBORAdapter
    Core -->|"translates"| FlexAdapter
    Core -->|"translates"| MsgpackAdapter
    Core -->|"translates"| TOMLAdapter
    Core -->|"translates"| UBJSONArrayAdapter
    Core -->|"translates"| XMLAdapter
    Core -->|"translates"| YAMLAdapter

    %% External Dependencies for Each Adapter
    JSONAdapter -->|"calls"| JSONExt["yyjson"]:::external
    AvroAdapter -->|"calls"| AvroExt["Avro Lib"]:::external
    BSONAdapter -->|"calls"| BSONExt["BSON Lib"]:::external
    CapnProtoAdapter -->|"calls"| CapnProtoExt["Cap'n Proto Lib"]:::external
    CBORAdapter -->|"calls"| CBORExt["CBOR Lib"]:::external
    FlexAdapter -->|"calls"| FlexExt["Flexbuffers Lib"]:::external
    MsgpackAdapter -->|"calls"| MsgpackExt["Msgpack Lib"]:::external
    TOMLAdapter -->|"calls"| TOMLExt["TOML Lib"]:::external
    UBJSONArrayAdapter -->|"calls"| UBJSONExt["UBJSON Lib"]:::external
    XMLAdapter -->|"calls"| XMLExt["pugixml"]:::external
    YAMLAdapter -->|"calls"| YAMLExt["YAML Lib"]:::external

    %% Quality Assurance Subgraph (Tests and Benchmarks)
    subgraph "Quality Assurance"
        TestSuite["Testing Framework"]:::test
        Benchmarks["Benchmarks"]:::test
    end

    %% Build & CI/CD and Documentation nodes
    BuildCI["Build & CI/CD"]:::build
    Docs["Documentation"]:::doc

    %% Relationships for QA, Build and Documentation
    Core ---|"validated by"| TestSuite
    JSONAdapter ---|"validated by"| TestSuite
    AvroAdapter ---|"validated by"| TestSuite
    BSONAdapter ---|"validated by"| TestSuite
    CapnProtoAdapter ---|"validated by"| TestSuite
    CBORAdapter ---|"validated by"| TestSuite
    FlexAdapter ---|"validated by"| TestSuite
    MsgpackAdapter ---|"validated by"| TestSuite
    TOMLAdapter ---|"validated by"| TestSuite
    UBJSONArrayAdapter ---|"validated by"| TestSuite
    XMLAdapter ---|"validated by"| TestSuite
    YAMLAdapter ---|"validated by"| TestSuite

    BuildCI ---|"builds and integrates"| Core
    BuildCI ---|"builds and integrates"| TestSuite
    Docs ---|"documents"| Core

    %% Click Events for Core Reflection Engine
    click Core "https://github.com/getml/reflect-cpp/blob/main/include/rfl.hpp"
    click Core "https://github.com/getml/reflect-cpp/tree/main/include/rfl/internal"

    %% Click Events for JSON Adapter
    click JSONAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_json.cpp"
    click JSONAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/json"

    %% Click Events for Avro Adapter
    click AvroAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_avro.cpp"
    click AvroAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/avro"

    %% Click Events for BSON Adapter
    click BSONAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_bson.cpp"
    click BSONAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/bson"

    %% Click Events for Cap'n Proto Adapter
    click CapnProtoAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_capnproto.cpp"
    click CapnProtoAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/capnproto"

    %% Click Events for CBOR Adapter
    click CBORAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_cbor.cpp"
    click CBORAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/cbor"

    %% Click Events for Flexbuffers Adapter
    click FlexAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_flexbuf.cpp"
    click FlexAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/flexbuf"

    %% Click Events for Msgpack Adapter
    click MsgpackAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_msgpack.cpp"
    click MsgpackAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/msgpack"

    %% Click Events for TOML Adapter
    click TOMLAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_toml.cpp"
    click TOMLAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/toml"

    %% Click Events for UBJSON Adapter
    click UBJSONArrayAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_ubjson.cpp"
    click UBJSONArrayAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/ubjson"

    %% Click Events for XML Adapter
    click XMLAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_xml.cpp"
    click XMLAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/xml"

    %% Click Events for YAML Adapter
    click YAMLAdapter "https://github.com/getml/reflect-cpp/blob/main/src/reflectcpp_yaml.cpp"
    click YAMLAdapter "https://github.com/getml/reflect-cpp/tree/main/include/rfl/yaml"

    %% Click Events for Testing Framework and Benchmarks
    click TestSuite "https://github.com/getml/reflect-cpp/tree/main/tests"
    click Benchmarks "https://github.com/getml/reflect-cpp/tree/main/benchmarks"

    %% Click Events for Build & CI/CD and Documentation
    click BuildCI "https://github.com/getml/reflect-cpp/blob/main/CMakeLists.txt"
    click BuildCI "https://github.com/getml/reflect-cpp/tree/main/.github/workflows"
    click Docs "https://github.com/getml/reflect-cpp/tree/main/docs"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px
    classDef adapter fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px
    classDef doc fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef user fill:#eafff5,stroke:#17a2b8,stroke-width:2px
```
