# elytrium/shipmc architecture

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

- Interactive diagram: https://gitdiagram.com/elytrium/shipmc
- Repository: https://github.com/elytrium/shipmc

## Overview

##### Project Type and Purpose
- ShipMC is a C++-based Minecraft protocol library combined with a proxy server (and “limbo” server) tool.
- It provides raw network abstractions (compression, framing), a full protocol parser/serializer (packets, data types, NBT, entities), and an executable proxy that sits between a Minecraft client and a real server.

##### File Structure Analysis
- Top level
- CMakeLists.txt, .gitignore, .clang-format → build and formatting
- .gitmodules → external submodule (lib/ShipNet)
- README.md, LICENSE
- lib/ShipNet
- A submodule providing foundational networking (socket wrappers, async I/O)
- src/Launcher.cpp
- Entry point for the proxy/limbo server
- src/main/proxy
- Proxy.cpp/.hpp → coordinates client⇄server connections
- client/Client.cpp/.hpp → represents the inbound Minecraft client connection
- handlers/… → per-packet handler classes (Connect, Status, Proxy)
- src/network/pipe
- CompressionPipe, MinecraftFramedBytePacketPipe → I/O pipeline layers: decompress/compress, frame split, raw packet I/O
- src/protocol
- MinecraftProtocol → high-level encode/decode orchestration
- ProtocolUtils → helpers for reading/writing primitives
- data/** → definitions of all in-game data structures (entities, items, world, NBT, particle, profile)
- handler/server → handshake/auth handlers for server-side protocol
- packet/** → all packet definitions for handshake, login, play, status, prepared
- registry → mapping between packet IDs and types
- src/utils
- ShipUtils, MinecraftOrdinalRegistry → miscellanous utilities and registries

##### Key Components
- Executable Layer
- Launcher (CLI application)
- Proxy module (accepts client sockets, spawns Client and Server sessions)
- Networking Layer (lib/ShipNet + src/network/pipe)
- TCP sockets
- CompressionPipe
- MinecraftFramedBytePacketPipe
- Raw byte ↔ Packet buffer
- Protocol Layer (src/protocol)
- PacketRegistry → determines packet type by ID
- Packet serializers/deserializers
- Data classes (Entity, ItemStack, NBT, etc.)
- Packet handlers (StatusPing, Handshake, LoginStart, Game packets)
- External Services
- Upstream Minecraft server (the real target)
- Downstream Minecraft client

##### Relationships and Data Flow
- Client <--TCP/connects to Launcher/Proxy Listener
- Proxy Listener hands off to a ClientSession object
- ClientSession I/O pipeline:
Socket → CompressionPipe → FramingPipe → Packet buffer → Protocol layer
- Protocol layer invokes appropriate PacketHandler
- e.g. HandshakePacketHandler → authenticates or redirects
- StatusPacketHandler → responds to pings
- ProxyPacketHandler → tunnels play-stage packets
- After decode and optional modification, packets are forwarded through the same pipeline back to client or upstream server.

##### Architectural Patterns and Principles
- Layered I/O pipeline (Decorator pattern): allows chaining compression, framing, byte-packet conversion
- Registry/Factory for packet IDs → PacketRegistry decouples ID lookup from class instantiation
- Handler pattern: each packet type has a handler class, making protocol extension modular
- Clear separation between networking, protocol parsing/serialization, and application logic

##### Final Advice
- Be exhaustive: include all major sub-systems (lib/ShipNet, network pipes, protocol handlers, data models).
- Both control flow (which component calls which handler) and data flow (how bytes travel).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Entities
  Client["Minecraft Client"]:::external
  Server["Upstream Minecraft Server"]:::external

  %% Executable Layer
  subgraph "Executable Layer"
    direction TB
    Launcher["Launcher (CLI)"]:::executable
    ProxyMod["Proxy Module"]:::executable
  end

  %% Networking Layer
  subgraph "Networking Layer"
    direction TB
    ShipNet["lib/ShipNet"]:::network
    PipeIF["MinecraftPipe Interface"]:::network
    CompPipe["CompressionPipe"]:::network
    FramePipe["MinecraftFramedBytePacketPipe"]:::network
  end

  %% Protocol Layer
  subgraph "Protocol Layer"
    direction TB
    Proto["MinecraftProtocol"]:::protocol
    Utils["ProtocolUtils"]:::protocol

    subgraph Registry
      direction TB
      PacketReg["PacketRegistry"]:::protocol
      BuiltInReg["BuiltInPacketRegistry"]:::protocol
    end

    subgraph "Data Models"
      direction TB
      DataModels["Data Definitions"]:::data
    end

    subgraph "Server-Side Handlers"
      direction TB
      PreAuthH["PreAuthPacketHandler"]:::protocol
      HandshakeH["ServerHandshakePacketHandler"]:::protocol
      PostAuthH["PostAuthPacketHandler"]:::protocol
      ServerH["ServerPacketHandler"]:::protocol
    end

    subgraph "Packet Definitions"
      direction TB
      Packets["Packet Definitions"]:::protocol
    end
  end

  %% Proxy Session
  subgraph "Proxy Session"
    direction TB
    ClientSess["ClientSession"]:::executable
    subgraph "Proxy Handlers"
      direction TB
      ConnectH["ConnectPacketHandler"]:::executable
      StatusH["StatusPacketHandler"]:::executable
      ProxyH["ProxyPacketHandler"]:::executable
    end
  end

  %% Utilities
  subgraph "Utilities"
    direction TB
    ShipUtils["ShipUtils"]:::protocol
    OrdinalReg["MinecraftOrdinalRegistry"]:::protocol
  end

  %% Connections
  Client -->|"TCP"| Launcher
  Launcher -->|"spawn Proxy Listener"| ProxyMod
  ProxyMod -->|"new session"| ClientSess
  ClientSess -->|"uses"| ShipNet
  ClientSess -->|"uses"| PipeIF
  ClientSess -->|"compress/decompress"| CompPipe
  ClientSess -->|"frame split"| FramePipe
  FramePipe -->|"Packets"| Proto
  Proto -->|"uses"| Utils
  Proto -->|"lookup ID"| PacketReg
  Proto -->|"lookup built-in"| BuiltInReg
  Proto -->|"deserialize"| Packets
  Packets -->|"create objects"| DataModels
  Proto -->|"invoke handler"| PreAuthH
  Proto -->|"invoke handler"| HandshakeH
  Proto -->|"invoke handler"| PostAuthH
  PreAuthH --> Proto
  HandshakeH --> Proto
  PostAuthH --> Proto
  Proto -->|"tunnel"| ConnectH
  Proto -->|"tunnel"| StatusH
  Proto -->|"tunnel"| ProxyH
  ConnectH --> Proto
  StatusH --> Proto
  ProxyH --> Proto
  Proto -->|"forward"| Server
  Proto -->|"respond"| Client

  %% Click Events
  click Launcher "https://github.com/elytrium/shipmc/blob/master/src/Launcher.cpp"
  click ProxyMod "https://github.com/elytrium/shipmc/blob/master/src/main/proxy/Proxy.cpp"
  click ClientSess "https://github.com/elytrium/shipmc/blob/master/src/main/proxy/client/Client.cpp"
  click ConnectH "https://github.com/elytrium/shipmc/blob/master/src/main/proxy/handlers/ConnectPacketHandler.cpp"
  click StatusH "https://github.com/elytrium/shipmc/blob/master/src/main/proxy/handlers/StatusPacketHandler.cpp"
  click ProxyH "https://github.com/elytrium/shipmc/blob/master/src/main/proxy/handlers/ProxyPacketHandler.hpp"
  click ShipNet "https://github.com/elytrium/shipmc/tree/master/lib/ShipNet"
  click CompPipe "https://github.com/elytrium/shipmc/blob/master/src/network/pipe/CompressionPipe.cpp"
  click FramePipe "https://github.com/elytrium/shipmc/blob/master/src/network/pipe/MinecraftFramedBytePacketPipe.cpp"
  click PipeIF "https://github.com/elytrium/shipmc/blob/master/src/network/pipe/MinecraftPipe.hpp"
  click Proto "https://github.com/elytrium/shipmc/blob/master/src/protocol/MinecraftProtocol.cpp"
  click Utils "https://github.com/elytrium/shipmc/blob/master/src/protocol/ProtocolUtils.cpp"
  click PacketReg "https://github.com/elytrium/shipmc/blob/master/src/protocol/registry/PacketRegistry.cpp"
  click BuiltInReg "https://github.com/elytrium/shipmc/blob/master/src/protocol/registry/BuiltInPacketRegistry.cpp"
  click DataModels "https://github.com/elytrium/shipmc/tree/master/src/protocol/data"
  click PreAuthH "https://github.com/elytrium/shipmc/blob/master/src/protocol/handler/server/PreAuthPacketHandler.cpp"
  click HandshakeH "https://github.com/elytrium/shipmc/blob/master/src/protocol/handler/server/ServerHandshakePacketHandler.cpp"
  click PostAuthH "https://github.com/elytrium/shipmc/blob/master/src/protocol/handler/server/PostAuthPacketHandler.cpp"
  click ServerH "https://github.com/elytrium/shipmc/blob/master/src/protocol/handler/server/ServerPacketHandler.hpp"
  click Packets "https://github.com/elytrium/shipmc/tree/master/src/protocol/packet"
  click ShipUtils "https://github.com/elytrium/shipmc/blob/master/src/utils/ShipUtils.cpp"
  click OrdinalReg "https://github.com/elytrium/shipmc/blob/master/src/utils/ordinal/MinecraftOrdinalRegistry.cpp"

  %% Styles
  classDef executable fill:#cce5ff,stroke:#339af0,color:#084298
  classDef network fill:#d3f9d8,stroke:#37b24d,color:#2f9e44
  classDef protocol fill:#ffe8cc,stroke:#f08c00,color:#a45c00
  classDef data fill:#fff3bf,stroke:#fcc419,color:#f08c00
  classDef external fill:#e9ecef,stroke:#adb5bd,color:#495057
```
