# emberemu/hexi architecture

> Architecture diagram of the GitHub repository emberemu/hexi, 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/emberemu/hexi
- Repository: https://github.com/emberemu/hexi

## Overview

##### Main Components
- Library API:
- The central “Hexi Library” component. Since the library is header‑only, this includes all the header files under the “include” and “single_include” directories. Emphasize that these files expose the primary classes (like binary_stream and buffer_adaptor) and additional helper utilities (e.g., static_buffer, dynamic_buffer, tls_block_allocator, file_buffer, and endian handling functionality).
- Unit Tests:
- “tests” directory as a separate component that uses the library’s API to validate functionality such as reading, writing, buffer adaptors, and endianness conversions.
- Documentation and Examples:
- A component for “Docs/Examples” (from the docs directory) that illustrates usage scenarios and practical examples (like handling DNS, STUN, GameSpy emulation, etc.).
- Build and Integration Tools:
- Build system (CMakeLists.txt at the root and in include/tests directories) and the CI setup (GitHub Workflows under .github/workflows). Additionally, include the “amalgamate” tool under the tools directory, which bundles the library into a single header if needed.

##### Relationships and Data Flow
- Library Internals:
– “buffer_adaptor”: Wraps any contiguous container (std::vector, std::array, etc.) to interface with binary_stream.
- Error handling:
- Conversion utilities:

- Interaction With External Containers:

- Application Integration Flow:
- For instance, show a data flow where:
"User’s Network Buffer" → wrapped by "buffer_adaptor" → processed by "binary_stream" → returns serialized/deserialized objects (like LoginPacket, LogoutPacket).

- Annotations for Key Decisions:
- Brief notes on why certain modules (like the amalgamate tool) exist and how the separate directories (tests, docs, tools) integrate into the overall project lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Hexi Library"]:::library

    subgraph "Hexi Library API"
        API1["binary_stream"]:::api
        API2["buffer_adaptor"]:::api
        API3["Endian Conversion Module"]:::api
        API4["Exception Handling"]:::api
        subgraph "Custom Buffers & Allocators"
            CB1["Static Buffer"]:::api
            CB2["Dynamic Buffer"]:::api
            CB3["File Buffer"]:::api
            CB4["TLS Block Allocator"]:::api
        end
    end

    NSF["Standard Library Containers"]:::external
    UNB["User's Network Buffer"]:::external
    SDO["Serialized/Deserialized Objects"]:::external

    subgraph "Build & Integration"
        BS["CMake Build System"]:::build
        CI["CI Setup"]:::build
        AM["Amalgamate Tool"]:::build
    end

    Tests["Unit Tests"]:::tests
    Docs["Docs/Examples"]:::docs

    %% High-level associations with Hexi Library
    A --- API1
    A --- API2
    A --- API3
    A --- API4
    A --- CB1
    A --- CB2
    A --- CB3
    A --- CB4

    %% Data flow from external sources through the API layers
    UNB -->|"wraps"| API2
    NSF -->|"used_by"| API2
    API2 -->|"provides_buffer_to"| API1
    API1 -->|"uses_endian"| API3
    API1 -->|"throws"| API4
    API1 -->|"produces"| SDO

    %% Integration / Testing and Documentation
    Tests -->|"tests"| API1
    Tests -->|"tests"| API2
    Docs -->|"demonstrates"| API1
    Docs -->|"demonstrates"| API2

    %% Build and Integration Connections
    A --- BS
    A --- CI
    A --- AM

    %% Click Events for Component Mappings
    click A "https://github.com/emberemu/hexi/tree/master/include/"
    click A "https://github.com/emberemu/hexi/tree/master/single_include/"
    click API1 "https://github.com/emberemu/hexi/blob/master/include/hexi/binary_stream.h"
    click API2 "https://github.com/emberemu/hexi/blob/master/include/hexi/buffer_adaptor.h"
    click API3 "https://github.com/emberemu/hexi/blob/master/include/hexi/endian.h"
    click API4 "https://github.com/emberemu/hexi/blob/master/include/hexi/exception.h"
    click CB1 "https://github.com/emberemu/hexi/blob/master/include/hexi/static_buffer.h"
    click CB2 "https://github.com/emberemu/hexi/blob/master/include/hexi/dynamic_buffer.h"
    click CB3 "https://github.com/emberemu/hexi/blob/master/include/hexi/file_buffer.h"
    click CB4 "https://github.com/emberemu/hexi/blob/master/include/hexi/allocators/tls_block_allocator.h"
    click Tests "https://github.com/emberemu/hexi/tree/master/tests/"
    click Docs "https://github.com/emberemu/hexi/tree/master/docs/"
    click BS "https://github.com/emberemu/hexi/blob/master/CMakeLists.txt"
    click CI "https://github.com/emberemu/hexi/tree/master/.github/workflows/"
    click AM "https://github.com/emberemu/hexi/tree/master/tools/amalgamate/"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef tests fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef docs fill:#FFDAB9,stroke:#000,stroke-width:1px;
    classDef build fill:#E0FFFF,stroke:#000,stroke-width:1px;
    classDef library fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
