# gerold103/serverbox architecture

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

- Interactive diagram: https://gitdiagram.com/gerold103/serverbox
- Repository: https://github.com/gerold103/serverbox

## Overview

##### Project Type and Purpose
- This is a C++ framework (library) for high-performance asynchronous networking and task scheduling, analogous to Boost.Asio but far more compact and optimized.
- Core modules:
- `IOCore` (async networking/event loop)
- `TaskScheduler` (multi-threaded async task engine)
- `net` and `sio` modules (socket abstractions)
- Supporting components: benchmarks (`bench/`), examples (`examples/`), unit tests (`test/`), formal specs (`tla/`), build/config (CMake, GitHub Actions).

##### High-Level Directory Structure and Architectural Patterns
- Low-level utilities (Atomics, Queues, Mutexes, Coroutines, Logging)
- Provides foundational primitives used everywhere else.
- src/mg/net:
- Protocol-agnostic I/O buffers, URL resolution, SSL abstractions.
- src/mg/sio:
- Simple socket and TCP server/client wrappers.
- src/mg/sch:
- TaskScheduler engine (tasks, scheduling queues).
- src/mg/aio:
- IOCore event loop, socket subscription interface, support for epoll, io_uring, kqueue, IOCP.
- src/mg/stub:
- test/:
- Unit tests for each module using CMake-driven test executables.
- bench/:
- Performance benchmarks for IOCore, MPSC/MPSC queues, TaskScheduler, I/O modes.
- examples/:
- Sample applications demonstrating TCP hello, SSL, pipelines, periodic tasks, coroutine tasks, interacting tasks.
- tla/:
- TLA+ specifications for core algorithms (TaskScheduler, MCSPQueue, InterruptibleMutex).

##### Core Components and Interactions
- Atomic queues, thread pools, condition variables, coroutines form the base.
b. net → sio & aio
- Core networking (Buffer, Socket, SSLContext) feeds into simplified I/O wrappers and the IOCore engine.
c. sch → aio
- TaskScheduler’s queueing and thread-dispatch logic is shared by IOTasks in IOCore.
d. aio ↔ OS kernel
- Event sources (epoll, io_uring, kqueue, IOCP) drive IOTasks, which then schedule callbacks via the scheduler.
e. Applications (examples/) and tests (test/) link against these libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers
    Examples["examples/"]:::consumers
    Tests["test/"]:::consumers
    Bench["bench/"]:::consumers

    %% Event Loop & Scheduler Layer
    Aio["libmgaio / IOCore"]:::schaio
    Sch["libmgsch"]:::schaio
    Sio["libmgsio"]:::networking

    %% Networking Layer
    Net["libmgnet"]:::networking

    %% Primitives Layer
    Box["libmgbox"]:::primitives

    %% Stub Libraries
    Stub["libmgboxstub / libmgsslstub"]:::external

    %% External Services
    OpenSSL["OpenSSL"]:::external
    KernelEpoll["epoll"]:::external
    KernelIOUring["io_uring"]:::external
    KernelKqueue["kqueue"]:::external
    KernelIOCP["IOCP"]:::external

    %% Relationships
    Box -->|"Atomics/Mutex"| Net
    Box -->|"ThreadPool/Queues"| Sch
    Box -->|"Coroutines/Logging"| Aio

    Net -->|"Buffer/Socket APIs"| Sio
    Net -->|"Buffer/Socket APIs"| Aio
    Net -->|"SSLContext"| OpenSSL

    Sch -->|"PostTask()"| Aio

    Aio -->|"IOCore::Run() / register"| KernelEpoll
    Aio -->|"IOCore::Run() / register"| KernelIOUring
    Aio -->|"IOCore::Run() / register"| KernelKqueue
    Aio -->|"IOCore::Run() / register"| KernelIOCP
    KernelEpoll <-->|"event callback"| Aio
    KernelIOUring <-->|"event callback"| Aio
    KernelKqueue <-->|"event callback"| Aio
    KernelIOCP <-->|"event callback"| Aio

    %% Consumers linking
    Examples -.->|"link with"| Aio
    Examples -.->|"link with"| Sch
    Examples -.->|"link with"| Net
    Examples -.->|"link with"| Box

    Tests -.->|"link with"| Aio
    Tests -.->|"link with"| Sch
    Tests -.->|"link with"| Net
    Tests -.->|"link with"| Box

    Bench -.->|"link with"| Aio
    Bench -.->|"link with"| Sch
    Bench -.->|"link with"| Net
    Bench -.->|"link with"| Box

    %% Stub injection
    Stub -.->|"logging/SSL hooks"| Box
    Stub -.->|"SSL stubs"| Net

    %% Click Events
    click Box "https://github.com/gerold103/serverbox/tree/master/src/mg/box/"
    click Net "https://github.com/gerold103/serverbox/tree/master/src/mg/net/"
    click Sio "https://github.com/gerold103/serverbox/tree/master/src/mg/sio/"
    click Sch "https://github.com/gerold103/serverbox/tree/master/src/mg/sch/"
    click Aio "https://github.com/gerold103/serverbox/tree/master/src/mg/aio/"
    click Stub "https://github.com/gerold103/serverbox/tree/master/src/mg/stub/"
    click Examples "https://github.com/gerold103/serverbox/tree/master/examples/"
    click Tests "https://github.com/gerold103/serverbox/tree/master/test/"
    click Bench "https://github.com/gerold103/serverbox/tree/master/bench/"

    %% Styles
    classDef primitives fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef networking fill:#B2DFDB,stroke:#333,stroke-width:1px
    classDef schaio fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef consumers fill:#E0E0E0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
