# navining/zeus architecture

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

- Interactive diagram: https://gitdiagram.com/navining/zeus
- Repository: https://github.com/navining/zeus

## Overview

1. **What this repository is**
   Zeus is a C++ networking engine, not an application. Its core purpose is to provide a cross-platform TCP communication layer built directly on native socket APIs, with no third-party runtime dependencies.

2. **Top-level structure**
   The repository is split into three meaningful areas:
   - `net/`: the networking engine itself
   - `utils/`: support infrastructure for performance, concurrency, config, logging, and timing
   - `examples/`: a minimal TCP client/server pair used to demonstrate and validate the engine

3. **Core networking layer**
   The `net/` directory is the main architecture boundary. It contains the abstractions for sockets, event handling, connection management, and multiplexing backends. This is where the engine turns OS-level socket activity into higher-level connection logic.

4. **I/O multiplexing backends**
   Zeus supports multiple event-demultiplexing models through separate backend implementations:
   - `Epoll.*` for Linux
   - `Select.*` for portable fallback
   - `IO.*` and `Event.h` as the abstraction layer around readiness/dispatch
   The README also mentions `IOCP` as planned, but it is not present here.

5. **Connection lifecycle**
   The main connection-oriented classes are:
   - `TcpClient.*`: client-side connection establishment and communication
   - `TcpServer.*`: listening socket, accept loop, and server-side orchestration
   - `TcpConnection.*`: per-connection state and I/O handling
   - `TcpSubserver.*`: likely a worker/partitioned server component used to scale handling across threads or sub-loops
   This suggests the architecture centers on managing many concurrent TCP sessions with per-connection state objects.

6. **Data movement and framing**
   `Buffer.*`, `Stream.*`, and `Message.h` define the data path above raw sockets:
   - `Buffer` is the byte storage used for receive/send paths
   - `Stream` likely provides higher-level read/write helpers over buffers
   - `Message` represents application payloads or protocol units
   The engine appears to separate transport I/O from message handling, which is important for diagramming the data flow.

7. **Concurrency and task execution**
   The `utils/` layer provides the concurrency primitives that support scaling:
   - `Thread.*` for thread abstraction
   - `Semaphore.*` for coordination
   - `TaskHandler.*` for deferred or background work
   - `Timestamp.*` for timing and timeout-related logic
   This indicates the engine is not purely single-threaded; it has infrastructure for threaded execution around the I/O core.

8. **Memory and object reuse**
   Performance-oriented allocation is a first-class concern:
   - `Allocator.h`
   - `MemoryPool.*`
   - `ObjectPool.h`
   These are used to reduce heap churn and improve throughput under high connection counts, which matches the README’s emphasis on large-scale concurrency.

9. **Configuration, logging, and observability**
   Operational support lives in `utils/Config.*`, `utils/Log.*`, and `utils/Timestamp.*`.
   - `Config` provides runtime/environment settings
   - `Log` gives the “complete and detailed log system” described in the README
   - `Timestamp` supports timeout, heartbeat, and telemetry-style timing
   These are supporting services rather than business logic, but they matter in the architecture because they drive runtime behavior and troubleshooting.

10. **Cross-platform boundary**
    The portability boundary is the OS socket and event API layer. The repository targets Windows, Linux, and macOS, with the backend code selecting between platform-specific I/O models while keeping the higher-level client/server API consistent.

11. **Example applications**
    `examples/client` and `examples/server` are small reference programs:
    - the server is an echo server
    - the client exercises the TCP stack
    They are useful for understanding the intended call flow: configure → start server/client → send messages → receive echo → log activity.

12. **Build and deployment shape**
    The repository is built with CMake on Unix-like systems and Visual Studio projects on Windows. The examples are the main buildable targets shown in the tree, and the README notes generated executables are placed under `bin/`.

13. **Architectural takeaway for a diagram**
    A good diagram would show:
    - application code at the top
    - client/server APIs in `net/`
    - a shared I/O abstraction layer selecting `select` or `epoll`
    - per-connection buffers and connection objects
    - support services in `utils/` for pools, threads, logging, and config
    - the operating system socket layer at the bottom
    There are no external services or middleware dependencies; the engine is self-contained and talks directly to the OS networking stack.

Main entry points: [`net/Network.h`](https://github.com/navining/zeus/blob/master/net/Network.h) (Network), [`net/TcpServer.h`](https://github.com/navining/zeus/blob/master/net/TcpServer.h) (TcpServer), [`net/TcpConnection.h`](https://github.com/navining/zeus/blob/master/net/TcpConnection.h) (TcpConnection), [`net/IO.h`](https://github.com/navining/zeus/blob/master/net/IO.h) (IO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_examples["examples"]
  node_client_app["Client<br/>example app<br/>[client.cpp]"]
  node_server_app["Server<br/>example app<br/>[server.cpp]"]
end

subgraph group_net["net"]
  node_network_facade["Network<br/>engine entry<br/>[Network.h]"]
  node_tcp_client["TcpClient<br/>client api<br/>[TcpClient.h]"]
  node_tcp_server["TcpServer<br/>server api<br/>[TcpServer.h]"]
  node_tcp_subserver["TcpSubserver<br/>server worker<br/>[TcpSubserver.h]"]
  node_tcp_connection["TcpConnection<br/>session state<br/>[TcpConnection.h]"]
  node_buffer["Buffer<br/>[Buffer.h]"]
  node_io_abstraction["IO<br/>dispatch layer<br/>[IO.h]"]
  node_event["Event<br/>[Event.h]"]
  node_epoll_backend["Epoll<br/>linux backend<br/>[Epoll.h]"]
  node_select_backend["Select<br/>portable backend<br/>[Select.h]"]
end

subgraph group_utils["utils"]
  node_stream["Stream<br/>io helper<br/>[Stream.h]"]
  node_message["Message<br/>payload model<br/>[Message.h]"]
  node_thread["Thread<br/>concurrency<br/>[Thread.h]"]
  node_semaphore(("Semaphore<br/>sync primitive<br/>[Semaphore.h]"))
  node_task_handler["TaskHandler<br/>background work<br/>[TaskHandler.h]"]
  node_memory_pool[("MemoryPool<br/>allocator pool<br/>[MemoryPool.h]")]
  node_object_pool[("ObjectPool<br/>object reuse<br/>[ObjectPool.h]")]
  node_config["Config<br/>[Config.h]"]
  node_log["Log<br/>observability<br/>[Log.h]"]
  node_timestamp(("Timestamp<br/>timing<br/>[Timestamp.h]"))
end

node_os_socket{{"OS sockets<br/>platform layer"}}

node_client_app -->|"uses"| node_network_facade
node_server_app -->|"uses"| node_network_facade
node_network_facade -->|"exposes"| node_tcp_client
node_network_facade -->|"exposes"| node_tcp_server
node_tcp_server -->|"scales"| node_tcp_subserver
node_tcp_client -->|"creates"| node_tcp_connection
node_tcp_server -->|"accepts"| node_tcp_connection
node_tcp_connection -->|"uses"| node_buffer
node_buffer -->|"adapts to"| node_stream
node_stream -->|"moves"| node_message
node_tcp_connection -->|"dispatches via"| node_io_abstraction
node_io_abstraction -->|"models"| node_event
node_io_abstraction -->|"selects"| node_epoll_backend
node_io_abstraction -->|"selects"| node_select_backend
node_epoll_backend -->|"calls"| node_os_socket
node_select_backend -->|"calls"| node_os_socket
node_tcp_server -->|"runs on"| node_thread
node_tcp_server -->|"coordinates"| node_semaphore
node_tcp_server -->|"offloads"| node_task_handler
node_tcp_connection -->|"allocates from"| node_memory_pool
node_tcp_connection -->|"reuses"| node_object_pool
node_network_facade -->|"configured by"| node_config
node_network_facade -->|"reports to"| node_log
node_network_facade -->|"times with"| node_timestamp

click node_client_app "https://github.com/navining/zeus/blob/master/examples/client/client.cpp"
click node_server_app "https://github.com/navining/zeus/blob/master/examples/server/server.cpp"
click node_network_facade "https://github.com/navining/zeus/blob/master/net/Network.h"
click node_tcp_client "https://github.com/navining/zeus/blob/master/net/TcpClient.h"
click node_tcp_server "https://github.com/navining/zeus/blob/master/net/TcpServer.h"
click node_tcp_subserver "https://github.com/navining/zeus/blob/master/net/TcpSubserver.h"
click node_tcp_connection "https://github.com/navining/zeus/blob/master/net/TcpConnection.h"
click node_buffer "https://github.com/navining/zeus/blob/master/net/Buffer.h"
click node_stream "https://github.com/navining/zeus/blob/master/utils/Stream.h"
click node_message "https://github.com/navining/zeus/blob/master/utils/Message.h"
click node_io_abstraction "https://github.com/navining/zeus/blob/master/net/IO.h"
click node_event "https://github.com/navining/zeus/blob/master/net/Event.h"
click node_epoll_backend "https://github.com/navining/zeus/blob/master/net/Epoll.h"
click node_select_backend "https://github.com/navining/zeus/blob/master/net/Select.h"
click node_thread "https://github.com/navining/zeus/blob/master/utils/Thread.h"
click node_semaphore "https://github.com/navining/zeus/blob/master/utils/Semaphore.h"
click node_task_handler "https://github.com/navining/zeus/blob/master/utils/TaskHandler.h"
click node_memory_pool "https://github.com/navining/zeus/blob/master/utils/MemoryPool.h"
click node_object_pool "https://github.com/navining/zeus/blob/master/utils/ObjectPool.h"
click node_config "https://github.com/navining/zeus/blob/master/utils/Config.h"
click node_log "https://github.com/navining/zeus/blob/master/utils/Log.h"
click node_timestamp "https://github.com/navining/zeus/blob/master/utils/Timestamp.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_app,node_server_app toneBlue
class node_network_facade,node_tcp_client,node_tcp_server,node_tcp_subserver,node_tcp_connection,node_buffer,node_io_abstraction,node_event,node_epoll_backend,node_select_backend toneAmber
class node_stream,node_message,node_thread,node_semaphore,node_task_handler,node_memory_pool,node_object_pool,node_config,node_log,node_timestamp toneMint
class node_os_socket toneNeutral
```

## Components

### examples

Reference client/server programs

- [Client](https://github.com/navining/zeus/blob/master/examples/client/client.cpp): example app · TCP example client · `examples/client/client.cpp`
- [Server](https://github.com/navining/zeus/blob/master/examples/server/server.cpp): example app · TCP echo server example · `examples/server/server.cpp`

### net

Core networking engine

- [Network](https://github.com/navining/zeus/blob/master/net/Network.h): engine entry · Top-level networking API and initialization · `net/Network.h`
- [TcpClient](https://github.com/navining/zeus/blob/master/net/TcpClient.h): client api · Client-side connection setup and messaging · `net/TcpClient.h`
- [TcpServer](https://github.com/navining/zeus/blob/master/net/TcpServer.h): server api · Listening socket and server orchestration · `net/TcpServer.h`
- [TcpSubserver](https://github.com/navining/zeus/blob/master/net/TcpSubserver.h): server worker · Partitioned server or worker loop · `net/TcpSubserver.h`
- [TcpConnection](https://github.com/navining/zeus/blob/master/net/TcpConnection.h): session state · Per-connection state and I/O handling · `net/TcpConnection.h`
- [Buffer](https://github.com/navining/zeus/blob/master/net/Buffer.h): byte buffer · Read/write byte storage · `net/Buffer.h`
- [IO](https://github.com/navining/zeus/blob/master/net/IO.h): dispatch layer · Readiness and event dispatch abstraction · `net/IO.h`
- [Event](https://github.com/navining/zeus/blob/master/net/Event.h): event model · Event representation used by the I/O layer · `net/Event.h`
- [Epoll](https://github.com/navining/zeus/blob/master/net/Epoll.h): linux backend · Linux epoll multiplexing backend · `net/Epoll.h`
- [Select](https://github.com/navining/zeus/blob/master/net/Select.h): portable backend · Portable select-based fallback backend · `net/Select.h`

### utils

Support infrastructure

- [Stream](https://github.com/navining/zeus/blob/master/utils/Stream.h): io helper · Higher-level read/write helpers over buffers · `utils/Stream.h`
- [Message](https://github.com/navining/zeus/blob/master/utils/Message.h): payload model · Application message or protocol unit · `utils/Message.h`
- [Thread](https://github.com/navining/zeus/blob/master/utils/Thread.h): concurrency · Thread abstraction · `utils/Thread.h`
- [Semaphore](https://github.com/navining/zeus/blob/master/utils/Semaphore.h): sync primitive · Coordination primitive · `utils/Semaphore.h`
- [TaskHandler](https://github.com/navining/zeus/blob/master/utils/TaskHandler.h): background work · Deferred or asynchronous task execution · `utils/TaskHandler.h`
- [MemoryPool](https://github.com/navining/zeus/blob/master/utils/MemoryPool.h): allocator pool · Pooled allocation for throughput · `utils/MemoryPool.h`
- [ObjectPool](https://github.com/navining/zeus/blob/master/utils/ObjectPool.h): object reuse · Reusable object storage · `utils/ObjectPool.h`
- [Config](https://github.com/navining/zeus/blob/master/utils/Config.h): runtime config · Runtime and environment settings · `utils/Config.h`
- [Log](https://github.com/navining/zeus/blob/master/utils/Log.h): observability · Logging and diagnostics · `utils/Log.h`
- [Timestamp](https://github.com/navining/zeus/blob/master/utils/Timestamp.h): timing · Timeout and timing support · `utils/Timestamp.h`

### Other components

- **OS sockets**: platform layer · Native socket and event APIs provided by the operating system

## Connections

- Client → Network: uses · Example client enters the engine API
- Server → Network: uses · Example server starts the engine
- Network → TcpClient: exposes · Shared top-level API for client operations
- Network → TcpServer: exposes · Shared top-level API for server operations
- TcpServer → TcpSubserver: scales · Server may shard work into subservers or loops
- TcpClient → TcpConnection: creates · Client establishes a session object for I/O
- TcpServer → TcpConnection: accepts · Accepted sockets become connection state
- TcpConnection → Buffer: uses · Connection I/O moves through buffers
- Buffer → Stream: adapts to · Streams build on buffer operations
- Stream → Message: moves · Stream helpers carry message payloads
- TcpConnection → IO: dispatches via · Connection activity is driven by readiness events
- IO → Event: models · Events are normalized for dispatch
- IO → Epoll: selects · Linux backend implementation
- IO → Select: selects · Portable fallback backend
- Epoll → OS sockets: calls · Backend talks to native OS APIs
- Select → OS sockets: calls · Fallback backend talks to native OS APIs
- TcpServer → Thread: runs on · Server work can be threaded
- TcpServer → Semaphore: coordinates · Coordination between workers or loops
- TcpServer → TaskHandler: offloads · Deferred work can be scheduled
- TcpConnection → MemoryPool: allocates from · Connection objects or buffers are pooled
- TcpConnection → ObjectPool: reuses · Session-related objects are recycled
- Network → Config: configured by · Runtime settings shape engine behavior
- Network → Log: reports to · Operational logging spans the engine
- Network → Timestamp: times with · Timeouts and timing are managed centrally
