# possseidon/unbound architecture

> Architecture diagram of the GitHub repository possseidon/unbound, 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/possseidon/unbound
- Repository: https://github.com/possseidon/unbound

## Overview

##### Project type and purpose
- Unbound is a multiplayer, Minecraft-inspired game/engine with smooth (marching-cubes) terrain built atop the Bevy game engine.
- It follows a client–server architecture: a GUI client for players, and a headless dedicated server.

##### File structure
- Top-level workspace (Cargo.toml) with four Rust crates:
- unbound-client – the Bevy-based game executable (can also host local servers)
- unbound-server – a headless, dedicated-server executable
- unbound-shared – code common to client & server (network protocol, world state, message types)
- unbound-lib – pure-Rust utilities (hexagonal chunking, marching cubes, math, change tracking)
- Standard Rust tooling and CI (GitHub Actions, rustfmt, dependabot) are present.

##### README for extra insights
- Explicit breakdown of the four crates and their dependencies.
- Emphasis on infinite smooth terrain, marching-cubes mesh generation, and modular crate design.

##### Essential details
- Crate dependency graph at top level.
- Drill into critical sub-modules in unbound-lib (hex_div, marching_cubes).
- Network boundary between client & server.
- Bevy ECS domain on the client.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    subgraph "Client Application"
        direction TB
        UCargo["Cargo.toml"]:::clientExec
        UMain["main.rs"]:::clientExec
        Bevy["Bevy Engine"]:::external
    end

    %% Server Application
    subgraph "Server Application"
        direction TB
        SCargo["Cargo.toml"]:::serverExec
        SMain["main.rs"]:::serverExec
    end

    %% Shared Library
    subgraph "Shared Library"
        direction TB
        SharedCargo["Cargo.toml"]:::shared
        SharedLibRs["lib.rs"]:::shared
    end

    %% Core Utilities Library
    subgraph "Core Utilities Library"
        direction TB
        CoreCargo["Cargo.toml"]:::core
        CoreLibRs["lib.rs"]:::core
        subgraph "Modules"
            direction TB
            ChangeTracking["change_tracking.rs"]:::core
            subgraph "hex_div"
                direction TB
                HexDivRs["hex_div.rs"]:::core
                Bounds["bounds.rs"]:::core
                Builder["builder.rs"]:::core
                Cache["cache.rs"]:::core
                Extent["extent.rs"]:::core
                Iter["iter.rs"]:::core
                Splits["splits.rs"]:::core
                Visit["visit.rs"]:::core
            end
            MarchingCubes["marching_cubes.rs"]:::core
            subgraph "math"
                direction TB
                MathRs["math.rs"]:::core
                MathBounds["bounds.rs"]:::core
                MathEnums["enums.rs"]:::core
            end
            Version["version.rs"]:::core
        end
    end

    %% External Networking
    Net["Network (TCP/UDP)"]:::external

    %% Connections
    UCargo -->|depends on| SharedCargo
    UMain -->|uses shared| SharedLibRs
    UCargo -->|depends on| CoreCargo
    UMain -->|uses core| CoreLibRs
    UMain -->|render/input| Bevy
    UMain -->|network messages| Net
    SCargo -->|depends on| SharedCargo
    SMain -->|uses shared| SharedLibRs
    SCargo -->|depends on| CoreCargo
    SMain -->|uses core| CoreLibRs
    SMain -->|network messages| Net
    SharedLibRs -->|message serialize/deserialize| Net
    CoreLibRs --> ChangeTracking
    CoreLibRs --> HexDivRs
    CoreLibRs --> MarchingCubes
    CoreLibRs --> MathRs
    CoreLibRs --> Version

    %% Click Events
    click UCargo "https://github.com/possseidon/unbound/blob/main/unbound-client/Cargo.toml"
    click UMain "https://github.com/possseidon/unbound/blob/main/unbound-client/src/main.rs"
    click SCargo "https://github.com/possseidon/unbound/blob/main/unbound-server/Cargo.toml"
    click SMain "https://github.com/possseidon/unbound/blob/main/unbound-server/src/main.rs"
    click SharedCargo "https://github.com/possseidon/unbound/blob/main/unbound-shared/Cargo.toml"
    click SharedLibRs "https://github.com/possseidon/unbound/blob/main/unbound-shared/src/lib.rs"
    click CoreCargo "https://github.com/possseidon/unbound/blob/main/unbound-lib/Cargo.toml"
    click CoreLibRs "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/lib.rs"
    click ChangeTracking "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/change_tracking.rs"
    click HexDivRs "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div.rs"
    click Bounds "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/bounds.rs"
    click Builder "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/builder.rs"
    click Cache "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/cache.rs"
    click Extent "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/extent.rs"
    click Iter "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/iter.rs"
    click Splits "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/splits.rs"
    click Visit "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/hex_div/visit.rs"
    click MarchingCubes "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/marching_cubes.rs"
    click MathRs "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/math.rs"
    click MathBounds "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/math/bounds.rs"
    click MathEnums "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/math/enums.rs"
    click Version "https://github.com/possseidon/unbound/blob/main/unbound-lib/src/version.rs"
    click docArch "https://github.com/possseidon/unbound/blob/main/doc/architecture.excalidraw"
    click docChunks "https://github.com/possseidon/unbound/blob/main/doc/chunk-boundaries.excalidraw"
    click docDensity "https://github.com/possseidon/unbound/blob/main/doc/density.excalidraw"

    %% Styles
    classDef clientExec fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef serverExec fill:#D0FFD6,stroke:#22863a,color:#22863a;
    classDef shared fill:#FFF2B2,stroke:#735c0f,color:#735c0f;
    classDef core fill:#E0E0E0,stroke:#586069,color:#586069;
    classDef external fill:#F0F0F0,stroke:#444,color:#444;
```
