# tigrux/traeger architecture

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

- Interactive diagram: https://gitdiagram.com/tigrux/traeger
- Repository: https://github.com/tigrux/traeger

## Overview

##### Project type and purpose
- Traeger is a **modular C++ library** (with Go and Python bindings) that implements the Actor Model, value‑semantics, serialization, and network messaging patterns.
- It is **not** a standalone application but a **library suite** meant to be embedded in client code (examples in C++, Go, Python).

##### File structure
- Top‑level CMake scripts and Dockerfiles: orchestrate building the core C++ libraries, Go bindings, Python bindings, and examples.
- `traeger/actor`, `traeger/format`, `traeger/socket`, `traeger/value`: the four **core modules** of the library.
- `python/` and `go/`: FFI layers exposing the core modules to Python (via Nanobind/CMake) and Go.
- `examples/`: sample client applications demonstrating usage patterns (value semantics, actors, serialization, socket patterns).
- `traeger/tests`: unit tests for each core module.

##### README insights
- Core modules correspond precisely to the Actor Model abstractions, serialization formats (JSON/YAML/MsgPack), ZeroMQ socket patterns (REQ/REP, PUB/SUB), and value‑types.
- External dependencies (immer, nlohmann/json, yaml‑cpp, msgpack‑c, ZeroMQ, nanobind) are **statically fetched** by CMake and link into the core libraries.

##### Main components
a. **Core C++ Libraries**:
- Actor module (Scheduler, Mailbox, Actor definitions, Promise/Result)
- Value module (Value, List, Map, Variant)
- Format module (Format interface, JSON/YAML/MsgPack adapters)
- Socket module (Context, Publisher, Subscriber, Requester, Replier)
b. **FFI Bindings**:
- Go bindings (`go/traeger_*.go`)
- Python bindings (`python/traeger_python.cpp/hpp` using Nanobind)
c. **External Dependencies**:
- ZeroMQ (network transport)
- nlohmann/json, yaml‑cpp, msgpack‑c (serialization)
- immer (persistent data structures)
- nanobind (Python binding)
d. **Client Applications**:
- C++ examples (in `examples/`)
- Go examples (`examples/go/`)
- Python examples (`examples/python/`)

##### Relationships and interactions
- **Actor module** uses **Value** types to carry message payloads.
- **Socket module** invokes the **Format** module to encode/decode Values over the network, then forwards requests to an Actor’s Mailbox.
- **Scheduler** (in Actor module) manages thread pools for concurrent execution of messages.
- FFI layers wrap the core modules, exposing the same abstractions in Go or Python.
- External dependencies feed into core modules at build time (e.g., Format → json/yaml/msgpack libraries; Socket → ZeroMQ).

##### Architectural patterns/design principles
- **Layered architecture**: Core modules at the center, FFI bindings around them, client apps at the outer layer.
- **Modular design**: Each module has its own directory, CMakeLists, tests.
- **Dependency inversion**: Core modules depend only on minimal standard C++ and abstract interfaces; concrete serializers/sockets are plugged in.
- **Actor Model**: mailboxes, promises, scheduler.
- **Zero‑MQ messaging patterns**: REQ/REP, PUB/SUB.

##### Essential elements without over‑splitting
- **four core modules**, **FFI layers**, **external dependencies**, and **client apps**.
- That all important interactions and dependencies are visible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Dependencies"
        ZMQ("ZeroMQ"):::cloud
        SER("JSON/YAML/MsgPack"):::cloud
        IMMER("immer"):::cloud
        NANOBIND("nanobind"):::cloud
    end

    subgraph "Core C++ Modules"
        ACTOR["traeger::actor"]:::actor
        VALUE["traeger::value"]:::value
        FORMAT["traeger::format"]:::format
        SOCKET["traeger::socket"]:::socket
    end

    subgraph "FFI Bindings"
        subgraph "Go Bindings"
            GO_ACTOR["Go: traeger_actor.go"]:::ffi
            GO_FORMAT["Go: traeger_format.go"]:::ffi
            GO_SOCKET["Go: traeger_socket.go"]:::ffi
            GO_VALUE["Go: traeger_value.go"]:::ffi
        end
        subgraph "Python Bindings"
            PY_CORE["Python: traeger_python.cpp"]:::ffi
            PY_HPP["Python: traeger_python.hpp"]:::ffi
            PY_ACTOR["Python: traeger_python_actor.cpp"]:::ffi
            PY_FORMAT["Python: traeger_python_format.cpp"]:::ffi
            PY_SOCKET["Python: traeger_python_socket.cpp"]:::ffi
            PY_VALUE["Python: traeger_python_value.cpp"]:::ffi
        end
    end

    subgraph "Client Applications"
        CPP_EX["C++ Examples"]:::client
        GO_EX["Go Examples"]:::client
        PY_EX["Python Examples"]:::client
    end

    ZMQ -->|transport| SOCKET
    SER -->|serialization libs| FORMAT
    IMMER -->|persistent DS| VALUE
    NANOBIND -->|binding| PY_CORE

    ACTOR -->|"uses Value for payloads"| VALUE
    SOCKET -->|"encode/decode"| FORMAT
    SOCKET -->|"forwards to Mailbox"| ACTOR

    SCHED["Scheduler"]:::actor
    SCHED -->|"executes messages"| ACTOR

    GO_ACTOR <--> ACTOR
    GO_FORMAT <--> FORMAT
    GO_SOCKET <--> SOCKET
    GO_VALUE <--> VALUE

    PY_CORE <--> ACTOR
    PY_CORE <--> VALUE
    PY_CORE <--> FORMAT
    PY_CORE <--> SOCKET
    PY_ACTOR <--> ACTOR
    PY_FORMAT <--> FORMAT
    PY_SOCKET <--> SOCKET
    PY_VALUE <--> VALUE

    CPP_EX --> ACTOR
    CPP_EX --> VALUE
    CPP_EX --> FORMAT
    CPP_EX --> SOCKET

    GO_EX --> GO_ACTOR
    GO_EX --> GO_FORMAT
    GO_EX --> GO_SOCKET
    GO_EX --> GO_VALUE

    PY_EX --> PY_CORE
    PY_EX --> PY_ACTOR
    PY_EX --> PY_FORMAT
    PY_EX --> PY_SOCKET
    PY_EX --> PY_VALUE

    click ACTOR "https://github.com/tigrux/traeger/tree/main/traeger/actor/"
    click VALUE "https://github.com/tigrux/traeger/tree/main/traeger/value/"
    click FORMAT "https://github.com/tigrux/traeger/tree/main/traeger/format/"
    click SOCKET "https://github.com/tigrux/traeger/tree/main/traeger/socket/"
    click GO_ACTOR "https://github.com/tigrux/traeger/blob/main/go/traeger_actor.go"
    click GO_FORMAT "https://github.com/tigrux/traeger/blob/main/go/traeger_format.go"
    click GO_SOCKET "https://github.com/tigrux/traeger/blob/main/go/traeger_socket.go"
    click GO_VALUE "https://github.com/tigrux/traeger/blob/main/go/traeger_value.go"
    click PY_CORE "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python.cpp"
    click PY_HPP "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python.hpp"
    click PY_ACTOR "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python_actor.cpp"
    click PY_FORMAT "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python_format.cpp"
    click PY_SOCKET "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python_socket.cpp"
    click PY_VALUE "https://github.com/tigrux/traeger/blob/main/python/traeger/traeger_python_value.cpp"
    click CPP_EX "https://github.com/tigrux/traeger/tree/main/examples/"
    click GO_EX "https://github.com/tigrux/traeger/tree/main/examples/go/"
    click PY_EX "https://github.com/tigrux/traeger/tree/main/examples/python/"

    classDef actor fill:#a8d5a2,stroke:#333,stroke-width:1px
    classDef value fill:#add8e6,stroke:#333,stroke-width:1px
    classDef format fill:#f9d29d,stroke:#333,stroke-width:1px
    classDef socket fill:#d8b4e2,stroke:#333,stroke-width:1px
    classDef ffi fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef client fill:#fff2b2,stroke:#333,stroke-width:1px
    classDef cloud fill:#cde5f7,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
