# mohanavel15/amethyst architecture

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

- Interactive diagram: https://gitdiagram.com/mohanavel15/amethyst
- Repository: https://github.com/mohanavel15/amethyst

## Overview

##### Project type and purpose
- Amethyst is a standalone Minecraft server implementation (targeting protocol version 1.8.x) written in Go.
- Its purpose is to accept Minecraft client connections, negotiate handshake/login, manage play-state sessions (chat, tab list, player position), and optionally handle status queries.

##### File structure
- Top-level:
- main.go: entrypoint
- go.mod, go.sum, LICENSE, README.md
- Packages:
- server/: core server components (connection management, context, encryption, authenticator, mux, player management)
- handlers/: per-state request handlers (echo/status, handshake, login, play)
- protocol/: packet definitions, state machine, serialization/deserialization, error types, “peeker” (frame reading)
- crypto/: CFB8 cipher, SHA1 for authentication
- zlib/: compression support
- Tests alongside most packages indicate unit-tested boundaries.

##### README
- Confirms it’s a fork of Plasma, implements Server Status, Join Game, Chat, Tab List, missing “spawn other players.”

##### Detail
- Every major package as a component
- State transitions (HANDSHAKING → LOGIN → PLAY)
- How Context/Player models are shared between handlers
- Call out external dependencies (e.g., Mojang Auth) even if not yet implemented
- Do not shy away from listing sub-packages (e.g., protocol/packets/status)

## Diagram (Mermaid)

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

    %% Core Server Layer
    subgraph "Core Server" 
        direction TB
        Main["Entrypoint (main.go)"]:::core
        ServerInit["Core Server Init (server/server.go)"]:::core
        ConnMgr["Connection Manager (server/conn.go)"]:::core
        StateMux["State Multiplexer (server/mux.go)"]:::core
        Authenticator["Authenticator (server/authenticator.go)"]:::core
        Encrypter["Encrypter (server/encrypter.go)"]:::core
        SessionCtx["Session Context (server/context.go)"]:::core
        PlayerModel["Player Model (server/player.go)"]:::core
    end

    %% Security & Compression Layer
    subgraph "Security / Compression" 
        direction TB
        Compression["Compression Layer (zlib/zlib.go)"]:::security
        CFB8["CFB8 Cipher (crypto/cfb8.go)"]:::security
        SHA1["SHA1 Auth (crypto/sha1.go)"]:::security
    end

    %% Protocol Engine Layer
    subgraph "Protocol Engine" 
        direction TB
        Peeker["Frame Peeker (protocol/peeker.go)"]:::protocol
        PacketDef["Packet Serializer/Defs (protocol/packet.go)"]:::protocol
        StateMachine["State Machine (protocol/state.go)"]:::protocol
        TypesErrors["Types & Errors (protocol/types.go, protocol/errors.go)"]:::protocol
        subgraph "Packet Groups"
            direction TB
            HS_Packets["Handshaking Packets (protocol/packets/handshaking/)"]:::protocol
            Login_Packets["Login Packets (protocol/packets/login/)"]:::protocol
            Play_Packets["Play Packets (protocol/packets/play/)"]:::protocol
            Status_Packets["Status Packets (protocol/packets/status/)"]:::protocol
        end
    end

    %% Handlers / Business Logic
    subgraph "Handlers" 
        direction TB
        HS_Handler["Handshake Handler (handlers/handshake.go)"]:::logic
        Login_Handler["Login Handler (handlers/login.go)"]:::logic
        Status_Handler["Status Handler (handlers/status.go)"]:::logic
        Echo_Handler["Echo Handler (handlers/echo.go)"]:::logic
        Play_Handler["Play Handler (handlers/play.go)"]:::logic
    end

    %% Tests (optional)
    subgraph "Tests" 
        direction TB
        ServerTests["Server Tests (server/server_test.go)"]:::test
        CryptoTests["Crypto Tests (crypto/cfb8_test.go, crypto/sha1_test.go)"]:::test
        HS_Tests["Handshaking Packet Tests (protocol/packets/handshaking/serverbound_handshake_test.go)"]:::test
    end

    %% Flow
    Client -->|"TCP Connect"| Main
    Main --> ServerInit
    ServerInit --> ConnMgr
    ConnMgr --> StateMux

    StateMux -->|"Inbound Bytes"| Peeker
    Peeker --> PacketDef
    PacketDef --> StateMachine
    StateMachine --> HS_Packets
    StateMachine --> Login_Packets
    StateMachine --> Play_Packets
    StateMachine --> Status_Packets

    HS_Packets --> HS_Handler
    Login_Packets --> Login_Handler
    Status_Packets --> Status_Handler
    Status_Packets --> Echo_Handler
    Play_Packets --> Play_Handler

    HS_Handler --> SessionCtx
    Login_Handler --> Authenticator
    Login_Handler --> SessionCtx
    Login_Handler --> PlayerModel
    Play_Handler --> PlayerModel
    Play_Handler --> SessionCtx

    HS_Handler --> PacketDef
    Login_Handler --> PacketDef
    Status_Handler --> PacketDef
    Echo_Handler --> PacketDef
    Play_Handler --> PacketDef

    PacketDef --> Compression
    Compression --> CFB8
    CFB8 --> SHA1
    SHA1 --> ConnMgr
    ConnMgr --> Client

    %% Click Events
    click Main "https://github.com/mohanavel15/amethyst/blob/main/main.go"
    click ConnMgr "https://github.com/mohanavel15/amethyst/blob/main/server/conn.go"
    click StateMux "https://github.com/mohanavel15/amethyst/blob/main/server/mux.go"
    click Authenticator "https://github.com/mohanavel15/amethyst/blob/main/server/authenticator.go"
    click Encrypter "https://github.com/mohanavel15/amethyst/blob/main/server/encrypter.go"
    click SessionCtx "https://github.com/mohanavel15/amethyst/blob/main/server/context.go"
    click PlayerModel "https://github.com/mohanavel15/amethyst/blob/main/server/player.go"
    click ServerInit "https://github.com/mohanavel15/amethyst/blob/main/server/server.go"
    click Peeker "https://github.com/mohanavel15/amethyst/blob/main/protocol/peeker.go"
    click PacketDef "https://github.com/mohanavel15/amethyst/blob/main/protocol/packet.go"
    click StateMachine "https://github.com/mohanavel15/amethyst/blob/main/protocol/state.go"
    click TypesErrors "https://github.com/mohanavel15/amethyst/blob/main/protocol/types.go"
    click HS_Packets "https://github.com/mohanavel15/amethyst/tree/main/protocol/packets/handshaking/"
    click Login_Packets "https://github.com/mohanavel15/amethyst/tree/main/protocol/packets/login/"
    click Play_Packets "https://github.com/mohanavel15/amethyst/tree/main/protocol/packets/play/"
    click Status_Packets "https://github.com/mohanavel15/amethyst/tree/main/protocol/packets/status/"
    click HS_Handler "https://github.com/mohanavel15/amethyst/blob/main/handlers/handshake.go"
    click Login_Handler "https://github.com/mohanavel15/amethyst/blob/main/handlers/login.go"
    click Status_Handler "https://github.com/mohanavel15/amethyst/blob/main/handlers/status.go"
    click Echo_Handler "https://github.com/mohanavel15/amethyst/blob/main/handlers/echo.go"
    click Play_Handler "https://github.com/mohanavel15/amethyst/blob/main/handlers/play.go"
    click Compression "https://github.com/mohanavel15/amethyst/blob/main/zlib/zlib.go"
    click CFB8 "https://github.com/mohanavel15/amethyst/blob/main/crypto/cfb8.go"
    click SHA1 "https://github.com/mohanavel15/amethyst/blob/main/crypto/sha1.go"
    click ServerTests "https://github.com/mohanavel15/amethyst/blob/main/server/server_test.go"
    click CryptoTests "https://github.com/mohanavel15/amethyst/blob/main/crypto/cfb8_test.go"
    click CryptoTests "https://github.com/mohanavel15/amethyst/blob/main/crypto/sha1_test.go"
    click HS_Tests "https://github.com/mohanavel15/amethyst/blob/main/protocol/packets/handshaking/serverbound_handshake_test.go"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef core fill:#d9edf7,stroke:#31708f,stroke-width:1px
    classDef security fill:#fcf8e3,stroke:#8a6d3b,stroke-width:1px
    classDef protocol fill:#f9f2f4,stroke:#c7254e,stroke-width:1px
    classDef logic fill:#dff0d8,stroke:#3c763d,stroke-width:1px
    classDef test fill:#eeeeee,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
```
