# yhisaki/wandb-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/yhisaki/wandb-cpp
- Repository: https://github.com/yhisaki/wandb-cpp

## Overview

- Library Core (C++ API): Represent the central component – the “wandbcpp” API – which provides key methods (init, update_config, log, finish). This is the public-facing API that client code calls.
- Python Binding/Integration Layer: Include elements like “py_object”, “np_object”, and “py_util” modules. These components provide the glue to call out to the Python wandb library (after a prerequisite pip installation of wandb).
- Object Wrappers for Logging: Illustrate components such as “wandb_object” and utilities (like handling images, videos, tables, and 3D objects). They are responsible for converting native C++ data types into forms that can be understood by the Python-based wandb.
- Examples/Demo Applications: In the “examples” directory there are various example applications each demonstrating different logging capabilities (time-series, images, videos, tables, and 3D objects). They serve as both test cases and usage documentation.

##### Relationships and Interactions
- The async handler then interacts with the Python binding/integration layer, converting the data via objects like “py_object” and “np_object”.
- The integration layer ultimately calls the underlying wandb Python functions (which are installed externally).

##### Architectural Patterns
- Asynchronous/multi-threaded design: Indicate that logging is handled in a separate thread or thread pool to ensure minimal performance impact.
- Wrapper pattern in the design: The project encapsulates Python functionalities inside C++ wrapper classes such as wandb_object.
- Layering – with a clear separation between the application-facing API (the “wandbcpp.hpp”) and the lower-level integration with the Python runtime.

##### Technologies and Tools
- CMake Build System: Represent the configuration files (e.g., CMakeLists.txt at both root and in the examples folder) indicating the build and configuration management.
- Optional OpenCV Integration: In the examples (when USE_OPENCV is turned on) and in image/video examples, mention the dependency on OpenCV to process and handle image/videodata.
- Mention Python and pip dependency for wandb (as verifying that the C++ binding depends on a functioning Python wandb environment).

## Diagram (Mermaid)

```mermaid
flowchart TD
    CA["Client Application (Examples)"]:::client
    API["Library Core (C++ API)"]:::api
    Async["Asynchronous Logging Module"]:::async
    Wrapper["Object Wrappers for Logging"]:::wrapper
    Py["Python Binding/Integration Layer"]:::py
    External["External wandb Service"]:::external
    Build["CMake Build System"]:::build
    Opencv["OpenCV (Optional)"]:::opencv

    %% Main vertical flow
    CA -->|"calls"| API
    API -->|"forwards"| Async
    Async -->|"invokes"| Wrapper
    Wrapper -->|"converts"| Py
    Py -->|"calls"| External

    %% Build system associations
    Build --- API
    Build --- CA
    Opencv --- CA

    %% Library Core file nodes
    API --> API1["wandbcpp.hpp"]:::api
    API --> API2["src/wandbcpp.cpp"]:::api

    %% Asynchronous Logging Module file nodes
    Async --> AL1["src/async_logging.cpp"]:::async
    Async --> AL2["src/async_logging.hpp"]:::async

    %% Object Wrappers for Logging file nodes
    Wrapper --> WR1["src/wandb_object.cpp"]:::wrapper
    Wrapper --> WR2["src/wandb_object.hpp"]:::wrapper

    %% Python Binding/Integration Layer file nodes
    Py --> PY1["src/py_object.cpp"]:::py
    Py --> PY2["src/py_object.hpp"]:::py
    Py --> PY3["src/np_object.cpp"]:::py
    Py --> PY4["src/np_object.hpp"]:::py
    Py --> PY5["src/py_util.cpp"]:::py
    Py --> PY6["src/py_util.hpp"]:::py

    %% Examples file nodes under Client Application
    CA --> EX1["examples/example_log_basic.cpp"]:::client
    CA --> EX2["examples/example_image.cpp"]:::client
    CA --> EX3["examples/example_video.cpp"]:::client
    CA --> EX4["examples/example_object3d.cpp"]:::client

    %% CMake Build System file nodes
    Build --> CMR["CMakeLists.txt (root)"]:::build
    Build --> CME["CMakeLists.txt (examples)"]:::build

    %% Click Events for Library Core
    click API1 "https://github.com/yhisaki/wandb-cpp/blob/master/wandbcpp.hpp"
    click API2 "https://github.com/yhisaki/wandb-cpp/blob/master/src/wandbcpp.cpp"

    %% Click Events for Asynchronous Logging Module
    click AL1 "https://github.com/yhisaki/wandb-cpp/blob/master/src/async_logging.cpp"
    click AL2 "https://github.com/yhisaki/wandb-cpp/blob/master/src/async_logging.hpp"

    %% Click Events for Object Wrappers for Logging
    click WR1 "https://github.com/yhisaki/wandb-cpp/blob/master/src/wandb_object.cpp"
    click WR2 "https://github.com/yhisaki/wandb-cpp/blob/master/src/wandb_object.hpp"

    %% Click Events for Python Binding/Integration Layer
    click PY1 "https://github.com/yhisaki/wandb-cpp/blob/master/src/py_object.cpp"
    click PY2 "https://github.com/yhisaki/wandb-cpp/blob/master/src/py_object.hpp"
    click PY3 "https://github.com/yhisaki/wandb-cpp/blob/master/src/np_object.cpp"
    click PY4 "https://github.com/yhisaki/wandb-cpp/blob/master/src/np_object.hpp"
    click PY5 "https://github.com/yhisaki/wandb-cpp/blob/master/src/py_util.cpp"
    click PY6 "https://github.com/yhisaki/wandb-cpp/blob/master/src/py_util.hpp"

    %% Click Events for Examples
    click EX1 "https://github.com/yhisaki/wandb-cpp/blob/master/examples/example_log_basic.cpp"
    click EX2 "https://github.com/yhisaki/wandb-cpp/blob/master/examples/example_image.cpp"
    click EX3 "https://github.com/yhisaki/wandb-cpp/blob/master/examples/example_video.cpp"
    click EX4 "https://github.com/yhisaki/wandb-cpp/blob/master/examples/example_object3d.cpp"

    %% Click Events for CMake Build System
    click CMR "https://github.com/yhisaki/wandb-cpp/blob/master/CMakeLists.txt (root)"
    click CME "https://github.com/yhisaki/wandb-cpp/blob/master/CMakeLists.txt (examples)"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef async fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef wrapper fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef py fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef opencv fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
