# t-x-t/oxide architecture

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

- Interactive diagram: https://gitdiagram.com/t-x-t/oxide
- Repository: https://github.com/t-x-t/oxide

## Overview

##### The custom Minecraft server (located in the server directory)
2. A proxy used for reverse engineering the Minecraft protocol (located in the proxy directory)
3. A shared library (in the lib directory) that encapsulates common functionality like packet serialization/deserialization, NBT handling, and utilities

##### Main Components
- Server Component: Represents the custom Minecraft server. Note that its code is in the server/src directory. Within the server, focus on the server module and its submodules, particularly how it handles incoming packets (see server/src/server/packet).
- Proxy Component: Represents the proxy application (proxy/src/main.rs) used for reverse engineering the Minecraft protocol. This serves as an intermediary that likely intercepts and analyzes traffic between clients and the server.
- Shared Library Component: This component, located in the lib directory, includes:
– Serialization and deserialization routines (serialize.rs, deserialize.rs, utils.rs)
– Detailed packet structures across various submodules (packets/clientbound and packets/serverbound, each with further subdivisions for login, play, configuration, handshaking, etc.)
– NBT (Named Binary Tag) handling, which is a key part of Minecraft data processing

- How the Server Component and Proxy Component both depend on the Shared Library for handling the Minecraft protocol.
– In the Server, incoming network connections are processed, packets are deserialized using routines from the lib module, and then routed to appropriate handlers in the server/packet submodules.
– The Proxy receives connections (or intercepts data) and similarly leverages the lib for decoding or reverse-engineering the protocol, potentially modifying or logging data before forwarding it.
- That the proxy may act as an intermediary between Minecraft clients and the server.

##### Architectural Patterns and Design Principles
- Modularity: The project is structured as separate modules (server, proxy, lib) that encapsulate different concerns.
- Separation of concerns: Notice how networking, protocol handling, and packet processing are neatly isolated.
- Layered architecture: The lib serves as the foundational layer for protocol operations, with both the server and proxy built on top of it.
- Use of well-named directories and module subdivisions (clientbound vs. serverbound packets) clearly reflects adherence to common design principles in protocol implementations.

##### Relevant Technologies and Frameworks
- Rust: Since all parts use Cargo.toml and source files with .rs extensions, Rust is the primary language.
- Network programming and asynchronous processing: Implicit in how the server and proxy handle packet flows.
- Possibly additional libraries (for serialization, network IO, etc.) as denoted in the Cargo files, though not explicitly listed.

##### Specific Elements
- "Custom Minecraft Server"
- "Proxy (Protocol Reverse Engineering)"
- "Shared Library (Protocol, Packets & NBT)"
- From clients → Proxy → Server, or possibly vice versa.
- Application entry points (e.g., main.rs for both server and proxy)
- Core library functions (packet structure, serialization/deserialization)
- Network and utility modules (e.g., NBT handling, utils)
- With notes on architectural patterns (e.g., “Modular Packet Processing”, “Layered Protocol Handling”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Minecraft Client
    Client["Minecraft Client"]:::client

    %% Proxy Component Subgraph
    subgraph "Proxy"
        ProxyMain["Proxy Main"]:::proxyMain
    end

    %% Custom Minecraft Server Subgraph
    subgraph "Custom Minecraft Server"
        ServerMain["Server Main"]:::serverMain
        PacketHandling["Packet Handling"]:::packet
        ServerMain -->|"initiates"| PacketHandling
    end

    %% Shared Library Subgraph
    subgraph "Shared Library (Protocol, Packets & NBT)"
        LibMain["Shared Library"]:::libMain
        Serialize["Serialize (serialize.rs)"]:::libModule
        Deserialize["Deserialize (deserialize.rs)"]:::libModule
        Utils["Utils (utils.rs)"]:::libModule
        NBT["NBT Handling"]:::libModule
        Packets["Packets (clientbound & serverbound)"]:::libModule
        LibMain --> Serialize
        LibMain --> Deserialize
        LibMain --> Utils
        LibMain --> NBT
        LibMain --> Packets
    end

    %% Data Flow between Components
    Client -->|"connects"| ProxyMain
    ProxyMain -->|"forwards traffic"| ServerMain
    ProxyMain -->|"leverages"| LibMain
    ServerMain -->|"utilizes"| LibMain
    PacketHandling -->|"processes via"| Packets
    ServerMain -->|"deserializes using"| Deserialize

    %% Click Events
    click ServerMain "https://github.com/t-x-t/oxide/blob/main/server/src/main.rs"
    click PacketHandling "https://github.com/t-x-t/oxide/tree/main/server/src/server/packet"
    click ProxyMain "https://github.com/t-x-t/oxide/blob/main/proxy/src/main.rs"
    click LibMain "https://github.com/t-x-t/oxide/tree/main/lib/src"
    click Serialize "https://github.com/t-x-t/oxide/blob/main/lib/src/serialize.rs"
    click Deserialize "https://github.com/t-x-t/oxide/blob/main/lib/src/deserialize.rs"
    click Utils "https://github.com/t-x-t/oxide/blob/main/lib/src/utils.rs"
    click NBT "https://github.com/t-x-t/oxide/tree/main/lib/src/nbt"
    click Packets "https://github.com/t-x-t/oxide/tree/main/lib/src/packets"

    %% Styles
    classDef client fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef proxyMain fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef serverMain fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef packet fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef libMain fill:#cce6ff,stroke:#003399,stroke-width:2px;
    classDef libModule fill:#e6f7ff,stroke:#0066cc,stroke-width:1px;
```
