# mas-bandwidth/netcode architecture

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

- Interactive diagram: https://gitdiagram.com/mas-bandwidth/netcode
- Repository: https://github.com/mas-bandwidth/netcode

## Overview

##### Main Components
- Client Component – Represented by files such as client.c, client_server.c, and profile.c, this part of the system handles the client-side connection initiation and communication. It also shows how a client retrieves a secure connect token (from an external REST API) and then establishes a connection.
- Server Component – Shown in server.c, the server is responsible for accepting client connections, managing a fixed pool of client slots, and handling secure communication. It uses a private key for encryption and decryption and coordinates client slots.
- Core Netcode Library – The core protocol logic is encapsulated in netcode.c/netcode.h. This includes the connection management, packet handling, and protocol states.
- Cryptographic Library (sodium) – The sodium subdirectory holds the extensive implementation of cryptography routines. This modular cryptography component is leveraged by the netcode library to provide encryption, signature verification, hash functions, and secure key exchange.
- Testing/Utility Components – Files like soak.c, test.cpp, and others serve for testing and benchmarking the network stability and performance.

- The communication channels should be depicted as unreliable UDP channels (unreliable and unordered), with an added layer providing encryption and signature validation.
- Interaction between the netcode protocol and the cryptography (sodium) module. You might show the netcode layer “calling” into sodium routines to perform encryption, hashing, or signing functions.
- If desired, also represent the interaction with an external REST API (for connect token generation) as an ancillary component that feeds into the client’s connection initiation process.

##### Architectural Patterns and Design Principles
- Connection-oriented over UDP: Emphasize that even though the underlying transport is UDP, the design offers features typically found in connection-oriented protocols, such as establishing sessions, reliable slot management, and secure client authentication.
- Modular Separation: The use of a dedicated cryptography module (sodium) indicates a clear separation of concerns. The network code leverages this module rather than implementing its own cryptography.
- Client Slot Management: The server holds a predefined number of client slots which is a notable architectural choice for managing simultaneous connections.

##### Relevant Technologies/Frameworks
- C Programming Language – The whole codebase is written in C, including manual memory management and using direct system calls (via sockets).
- UDP Sockets – As the network transport layer.
- Sodium Library – A well-known library for cryptographic functions (encryption, signing, etc.).
- CI/CD Tools – GitHub workflows for continuous integration, although not part of the runtime architecture, they are essential for development and build processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    token["Connect Token Service (REST API)"]:::external

    %% Client Component Subgraph
    subgraph "Client Component"
        direction TB
        a1["client.c"]:::client
        a2["client_server.c"]:::client
        a3["profile.c"]:::client
    end

    %% UDP Transport Node
    udp["UDP Transport (UDP Sockets)"]:::udp

    %% Server Component Subgraph
    subgraph "Server Component"
        direction TB
        s1["server.c"]:::server
    end

    %% Core Netcode Library Subgraph
    subgraph "Core Netcode Library (Netcode Protocol)"
        direction TB
        n1["netcode.c"]:::netcode
        n2["netcode.h"]:::netcode
    end

    %% Cryptographic Library (sodium)
    cry["sodium (Cryptography Module)"]:::crypto

    %% Build and Configuration Subgraph
    subgraph "Build and Configuration"
        direction TB
        b1["premake5.lua"]:::build
        b2["BUILDING.md"]:::build
        b3[".github/workflows/ci.yml"]:::build
    end

    %% Testing/Utility Components Subgraph
    subgraph "Testing/Utility Components"
        direction TB
        t1["soak.c"]:::test
        t2["test.cpp"]:::test
    end

    %% Relationships
    token -->|"retrieves_token"| a1
    a1 -->|"initiates_protocol"| n1
    a1 -->|"sends_packets"| udp
    udp -->|"delivers_packets"| s1
    s1 -->|"handles_connection"| n1
    n1 -->|"crypto_ops"| cry

    %% Click Events for Client Component
    click a1 "https://github.com/mas-bandwidth/netcode/blob/main/client.c"
    click a2 "https://github.com/mas-bandwidth/netcode/blob/main/client_server.c"
    click a3 "https://github.com/mas-bandwidth/netcode/blob/main/profile.c"

    %% Click Events for Server Component
    click s1 "https://github.com/mas-bandwidth/netcode/blob/main/server.c"

    %% Click Events for Core Netcode Library
    click n1 "https://github.com/mas-bandwidth/netcode/blob/main/netcode.c"
    click n2 "https://github.com/mas-bandwidth/netcode/blob/main/netcode.h"

    %% Click Event for Cryptographic Library
    click cry "https://github.com/mas-bandwidth/netcode/tree/main/sodium/"

    %% Click Events for Build and Configuration
    click b1 "https://github.com/mas-bandwidth/netcode/blob/main/premake5.lua"
    click b2 "https://github.com/mas-bandwidth/netcode/blob/main/BUILDING.md"
    click b3 "https://github.com/mas-bandwidth/netcode/blob/main/.github/workflows/ci.yml"

    %% Click Events for Testing/Utility Components
    click t1 "https://github.com/mas-bandwidth/netcode/blob/main/soak.c"
    click t2 "https://github.com/mas-bandwidth/netcode/blob/main/test.cpp"

    %% Styling Classes
    classDef client fill:#a2d2ff,stroke:#000,stroke-width:1px
    classDef server fill:#ffadad,stroke:#000,stroke-width:1px
    classDef netcode fill:#caffbf,stroke:#000,stroke-width:1px
    classDef crypto fill:#fdffb6,stroke:#000,stroke-width:1px
    classDef external fill:#d0f4de,stroke:#000,stroke-width:1px
    classDef udp fill:#f0efeb,stroke:#000,stroke-width:1px
    classDef build fill:#e0bbff,stroke:#000,stroke-width:1px
    classDef test fill:#ffbf69,stroke:#000,stroke-width:1px
```
