# pigbrain/hnet architecture

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

- Interactive diagram: https://gitdiagram.com/pigbrain/hnet
- Repository: https://github.com/pigbrain/hnet

## Overview

##### Project type and purpose
- This is a C++ socket-library (“HNet”) for Linux, exposing non-blocking TCP client/server abstractions, an epoll-based I/O manager, connector/link management, and a command framework.
- It is an open-source tool intended to be linked into sample applications (under `sample/`) or other C++ projects.

##### File structure
- Top-level directories:
- `inc/` – public headers (API surface)
- `src/` – implementation files corresponding to each header
- `sample/` – example client/server programs demonstrating library usage
- Key sub-domains (from file names):
- Low-level socket wrapping (`HSocket`, `HTCPSocket`, `HConnector`, `HLink`, `HEpoll`)
- I/O management (`HIOMgr`, `HTCPIOMgr`)
- Connection managers (`HClientMgr`, `HServerMgr`, `HTCPClientMgr`, `HTCPServerMgr`)
- Command framework (`HCommand`, `HCommandRouter`, `HCommandWorker`, `HCommandManager`, etc.)
- Concurrency primitives (`HMutex`, `HAtomicCounter`)
- Logging (`HNetLog`)

##### README
- Confirms the project is a “socket library for linux.”

a. Main components
1. Public API (HNetLib) – the entry point library that user programs link against
2. Transport layer
- Epoll Engine (HEpoll)
- Socket Abstractions (HSocket, HTCPSocket)
- Connector/Link (HConnector, HLink, HLinkMap)
3. I/O Manager
- Generic I/O Manager (HIOMgr)
- TCP-specific I/O Manager (HTCPIOMgr)
4. Connection Managers
- Client Manager (HClientMgr, HTCPClientMgr)
- Server Manager (HServerMgr, HTCPServerMgr)
5. Command Framework
- Command Descriptors & Tables (HCommandDesc, CommandTable_HNET)
- Command Routing and Workers (HCommandRouter, HCommandWorker, HCommandCommunicator, HCommandStream)
- Command Manager and Parameter Handling (HCommandManager, HCommandParameter)
6. Utilities
- Thread safety (HMutex, HAtomicCounter)
- Logging (HNetLog)

b. Relationships and data flow
- User App → links against HNetLib → calls into Connection Managers (ClientMgr/ServerMgr).
- Connection Manager registers sockets with I/O Manager → HIOMgr/HTCPIOMgr uses HEpoll to wait for events.
- Upon read/write events, HIOMgr dispatches data to HCommandCommunicator → CommandRouter → CommandWorker.
- Command results/errors propagate back through communicator to the socket/link.
- Utilities (HMutex, HAtomicCounter) protect shared state across threads; HNetLog logs events.

c. Architectural patterns
- Reactor pattern (HEpoll + HIOMgr)
- Factory/Manager pattern for clients and servers
- Command pattern for request/response handling
- Layered abstraction: transport → I/O management → command processing → public API

d. Technologies & frameworks
- C++ on Linux
- epoll system calls
- Makefiles for build (`src/Makefile`, `sample/Makefile`)

##### Detailed steps for the principal software engineer
2. Inside HNetLib, group 3 vertical sections: Transport, I/O Manager, Command Framework.
3. Under Transport: place HEpoll, HSocket/HTCPSocket, HConnector/HLink.
4. Under I/O Manager: HIOMgr → HTCPIOMgr.
5. Under Command Framework: HCommandManager, HCommandRouter, HCommandWorker, etc., plus descriptor/table.
6. Connection Managers between Transport and I/O Manager, showing how they wire sockets into the reactor loop.
8. Side-bars for utilities: HMutex, HAtomicCounter, HNetLog, indicating that they are used across all modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External entities
    UserApp(["User Application"]):::external
    LinuxKernel(["Linux Kernel (epoll)"]):::external
    SampleApps(["Sample Applications"]):::external

    %% Library core
    subgraph "HNetLib (Public API)" 
        direction TB

        subgraph "Transport Layer"
            direction TB
            HEpoll["HEpoll"]:::transport
            HSocket["HSocket / HTCPSocket"]:::transport
            HConnector["HConnector / HLink / HLinkMap"]:::transport
        end

        subgraph "Connection Managers"
            direction TB
            HClientMgr["HClientMgr / HTCPClientMgr"]:::coreRect
            HServerMgr["HServerMgr / HTCPServerMgr"]:::coreRect
        end

        subgraph "I/O Manager"
            direction TB
            HIOMgr["HIOMgr"]:::iomgr
            HTCPIOMgr["HTCPIOMgr"]:::iomgr
        end

        subgraph "Command Framework"
            direction TB
            HCommandManager["HCommandManager"]:::cmd
            HCommandRouter["HCommandRouter"]:::cmd
            HCommandWorker["HCommandWorker"]:::cmd
            HCommandCommunicator["HCommandCommunicator"]:::cmd
            HCommandStream["HCommandStream"]:::cmd
            HCommandDesc["HCommandDesc / CommandTable_HNET"]:::cmd
            HCommandParameter["HCommandParameter"]:::cmd
            HCommand["HCommand"]:::cmd
        end

    end

    subgraph "Utilities"
        direction TB
        HMutex["HMutex"]:::util
        HAtomicCounter["HAtomicCounter"]:::util
        HNetLog["HNetLog"]:::util
    end

    %% Flows
    UserApp -->|"links to API"| HClientMgr
    UserApp -->|"links to API"| HServerMgr
    HClientMgr -->|"register socket"| HIOMgr
    HServerMgr -->|"register socket"| HIOMgr
    HIOMgr -->|"epoll wait"| HEpoll
    HEpoll -->|"event"| HIOMgr
    HIOMgr -->|"dispatch event"| HCommandCommunicator
    HCommandCommunicator -->|"route"| HCommandRouter
    HCommandRouter -->|"execute"| HCommandWorker
    HCommandWorker -->|"callback"| HCommandCommunicator
    HCommandCommunicator -->|"send response"| HSocket
    HSocket -->|"data"| UserApp

    %% External interactions
    SampleApps -->|"use API"| UserApp
    LinuxKernel -->|"epoll syscall"| HEpoll

    %% Utilities usage
    HMutex -.-> HIOMgr
    HMutex -.-> HCommandManager
    HAtomicCounter -.-> HClientMgr
    HAtomicCounter -.-> HServerMgr
    HNetLog -.-> HEpoll
    HNetLog -.-> HCommandWorker

    %% Click events
    click HSocket "https://github.com/pigbrain/hnet/blob/master/inc/HSocket.h"
    click HSocket "https://github.com/pigbrain/hnet/blob/master/src/HSocket.cpp"
    click HEpoll "https://github.com/pigbrain/hnet/blob/master/inc/HEpoll.h"
    click HEpoll "https://github.com/pigbrain/hnet/blob/master/src/HEpoll.cpp"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/inc/HConnector.h"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/src/HConnector.cpp"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/inc/HLink.h"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/src/HLink.cpp"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/inc/HLinkMap.h"
    click HConnector "https://github.com/pigbrain/hnet/blob/master/src/HLinkMap.cpp"
    click HIOMgr "https://github.com/pigbrain/hnet/blob/master/inc/HIOMgr.h"
    click HIOMgr "https://github.com/pigbrain/hnet/blob/master/src/HIOMgr.cpp"
    click HTCPIOMgr "https://github.com/pigbrain/hnet/blob/master/inc/HTCPIOMgr.h"
    click HTCPIOMgr "https://github.com/pigbrain/hnet/blob/master/src/HTCPIOMgr.cpp"
    click HClientMgr "https://github.com/pigbrain/hnet/blob/master/inc/HClientMgr.h"
    click HClientMgr "https://github.com/pigbrain/hnet/blob/master/src/HClient.cpp"
    click HServerMgr "https://github.com/pigbrain/hnet/blob/master/inc/HServerMgr.h"
    click HServerMgr "https://github.com/pigbrain/hnet/blob/master/src/HServer.cpp"
    click HTCPClientMgr "https://github.com/pigbrain/hnet/blob/master/inc/HTCPClientMgr.h"
    click HTCPClientMgr "https://github.com/pigbrain/hnet/blob/master/src/HTCPClientMgr.cpp"
    click HTCPServerMgr "https://github.com/pigbrain/hnet/blob/master/inc/HTCPServerMgr.h"
    click HTCPServerMgr "https://github.com/pigbrain/hnet/blob/master/src/HTCPServerMgr.cpp"
    click HCommand "https://github.com/pigbrain/hnet/blob/master/inc/HCommand.h"
    click HCommand "https://github.com/pigbrain/hnet/blob/master/src/HCommand.cpp"
    click HCommandDesc "https://github.com/pigbrain/hnet/blob/master/inc/HCommandDesc.h"
    click HCommandDesc "https://github.com/pigbrain/hnet/blob/master/src/HCommandDesc.cpp"
    click HCommandDesc "https://github.com/pigbrain/hnet/blob/master/inc/CommandTable_HNET.h"
    click HCommandDesc "https://github.com/pigbrain/hnet/blob/master/src/CommandTable_HNET.cpp"
    click HCommandRouter "https://github.com/pigbrain/hnet/blob/master/inc/HCommandRouter.h"
    click HCommandRouter "https://github.com/pigbrain/hnet/blob/master/src/HCommandRouter.cpp"
    click HCommandWorker "https://github.com/pigbrain/hnet/blob/master/inc/HCommandWorker.h"
    click HCommandWorker "https://github.com/pigbrain/hnet/blob/master/src/HCommandWorker.cpp"
    click HCommandCommunicator "https://github.com/pigbrain/hnet/blob/master/inc/HCommandCommunicator.h"
    click HCommandCommunicator "https://github.com/pigbrain/hnet/blob/master/src/HCommandCommunicator.cpp"
    click HCommandStream "https://github.com/pigbrain/hnet/blob/master/inc/HCommandStream.h"
    click HCommandStream "https://github.com/pigbrain/hnet/blob/master/src/HCommandStream.cpp"
    click HCommandParameter "https://github.com/pigbrain/hnet/blob/master/inc/HCommandParameter.h"
    click HCommandParameter "https://github.com/pigbrain/hnet/blob/master/src/HCommandParameter.cpp"
    click HCommandManager "https://github.com/pigbrain/hnet/blob/master/inc/HCommandManager.h"
    click HCommandManager "https://github.com/pigbrain/hnet/blob/master/src/HCommandManager.cpp"
    click HMutex "https://github.com/pigbrain/hnet/blob/master/inc/HMutex.h"
    click HMutex "https://github.com/pigbrain/hnet/blob/master/src/HMutex.cpp"
    click HAtomicCounter "https://github.com/pigbrain/hnet/blob/master/inc/HAtomicCounter.h"
    click HAtomicCounter "https://github.com/pigbrain/hnet/blob/master/src/HAtomicCounter.cpp"
    click HNetLog "https://github.com/pigbrain/hnet/blob/master/inc/HNetLog.h"
    click HNetLog "https://github.com/pigbrain/hnet/blob/master/src/HNetLog.cpp"
    click SampleApps "https://github.com/pigbrain/hnet/tree/master/sample/"

    %% Styles
    classDef transport fill:#c3e6cb,stroke:#2e7d32,color:#1b5e20;
    classDef iomgr fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef cmd fill:#d1c4e9,stroke:#5e35b1,color:#311b92;
    classDef coreRect fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef util fill:#ffccbc,stroke:#d84315,color:#bf360c;
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f;
```
