Architecture Overview

graph LR
    Browser["Browser<br/>(Player)"] -- "UDP 5520<br/>QUIC" --> HS

    subgraph Docker["Docker Host"]
        HS["Hytale Server<br/>ghcr.io/editmysave/hyos/server"]
        API["API Plugin<br/>(inside HS)"]
        MGR["HyOS Manager<br/>ghcr.io/editmysave/hyos/manager"]

        HS --- API
        MGR -- "HTTP 8080<br/>REST API" --> API
        MGR -- "/var/run/docker.sock<br/>(read-only)" --> Docker_Daemon["Docker Daemon"]
        HS -- "/data volume<br/>(shared)" --> Vol[("/data")]
        MGR -- "/data volume<br/>(shared)" --> Vol
    end

    Admin["Browser<br/>(Admin)"] -- "HTTP 3000<br/>Web UI" --> MGR
    Docker_Daemon -- "start/stop/restart" --> HS

graph TD
    subgraph Server Container
        EP[Entrypoint Scripts] -->|writes| SF[State Files<br/>/data/.state/]
        EP -->|generates| CF[config.json]
        EP -->|manages| MODS[/data/mods/]
        JAVA[Java Server Process] -->|logs| LOGS[stdout/stderr]
        APIP[API Plugin] -->|reads| JAVA
    end

    subgraph Manager Container
        WEB[Next.js App] -->|reads| SF
        WEB -->|REST API| APIP
        WEB -->|Docker socket| DOCK[Docker Daemon]
    end

    subgraph Host
        VOL[/data Volume] --- SF
        VOL --- CF
        VOL --- MODS
        SOCK[docker.sock] --- DOCK
    end

    ADMIN[Admin Browser] -->|HTTP 3000| WEB
    PLAYER[Game Client] -->|UDP 5520| JAVA

/data/
├── server/                     # Server files (auto-managed)
│   ├── HytaleServer.jar        # Server executable
│   ├── HytaleServer.aot        # AOT compilation cache
│   ├── config.json             # Server configuration
│   ├── whitelist.json          # Player whitelist (if enabled)
│   ├── permissions.json        # Permission groups and assignments
│   ├── Licenses/               # Third-party licenses
│   ├── logs/                   # Server log files
│   ├── mods/                   # Plugin runtime data
│   │   └── com.hytale_HytaleAPI/
│   │       └── config.json     # API plugin config (bcrypt hashed)
│   └── universe/               # World data
│       ├── players/            # Per-player data (UUID.json)
│       └── worlds/
│           └── default/        # Default world
│               ├── config.json
│               ├── chunks/     # Region files
│               └── resources/
├── Assets.zip                  # Game assets (auto-managed)
├── mods/                       # User mods directory
│   ├── MyMod-1.0.0.jar
│   ├── hytale-api-1.0.0.jar   # API plugin (auto-installed)
│   └── .disabled/              # Quarantined broken mods
├── backups/                    # Automatic backups
├── logs/
│   └── auto-update.log         # Update history
├── .auth/                      # OAuth tokens (mode 700)
│   └── tokens.json             # Cached tokens (mode 600)
├── .state/                     # State files for Manager UI
│   ├── server.json
│   ├── version.json
│   ├── auth.json
│   ├── config.json
│   ├── health.json
│   ├── mods.json
│   ├── update.json
│   └── manager-config.json     # Manager settings
├── .version                    # Current server version string
├── .broken-mods                # Version-tagged broken mod list
└── .update-on-restart          # Scheduled update flag (JSON)

sequenceDiagram
    participant D as Docker
    participant T as Tini (init)
    participant E as Entrypoint
    participant A as Auth
    participant J as Java Server
    participant M as Mod Monitor

    D->>T: Start container
    T->>E: Execute entrypoint.sh
    E->>E: Architecture check (x86_64)
    E->>E: Permission check (/data writable)
    E->>E: Setup user (PUID/PGID)
    E->>E: Create directories
    E->>E: Initialize state files

    alt Scheduled update exists
        E->>E: Perform update
    end

    alt Server files missing
        E->>E: Download server files
    else AUTO_UPDATE=true
        E->>E: Check for updates
    end

    E->>E: Validate mods
    E->>E: Generate config.json
    E->>E: Generate API config
    E->>A: Authenticate

    alt Cached tokens valid
        A-->>E: Use cached tokens
    else Injected tokens
        A-->>E: Use env var tokens
    else No valid tokens
        A->>A: Device code flow (15 min timeout)
        A-->>E: New tokens
    end

    E->>E: Drop privileges (su-exec)
    E->>E: Start version checker (background)
    E->>J: Launch Java process
    E->>M: Start mod monitor (30s delay)

    loop Server Running
        J->>J: Handle game traffic
        M->>M: Parse logs for mod state
    end

    Note over E,J: SIGTERM → graceful shutdown

// server.json
interface ServerState {
  status: "starting" | "running" | "stopped" | "crashed" | "unknown";
  pid: number | null;
  started_at: string | null;  // ISO 8601
  updated_at: string;         // ISO 8601
}

// version.json
interface VersionState {
  current: string;
  latest: string | null;
  needs_update: boolean;
  checked_at: string;  // ISO 8601
}

// auth.json
interface AuthState {
  status: "authenticated" | "pending" | "failed" | "timeout" | "unknown";
  authenticated: boolean;
  profile: string | null;     // Username
  expires_at: string | null;  // ISO 8601
  updated_at: string;         // ISO 8601
  // Only present when status is "pending":
  url?: string;               // Device auth URL
  code?: string;              // User code
}

// config.json (state copy — not the server config)
interface ConfigState {
  config: {
    server_name: string;
    motd: string;
    max_players: number;
    max_view_radius: number;
    default_world: string;
    default_gamemode: string;
    whitelist_enabled: boolean;
    local_compression: boolean;
    has_password: boolean;      // Never the actual password
  };
  updated_at: string;
}

// health.json
interface HealthState {
  status: "healthy" | "unhealthy";
  healthy: boolean;
  message: string;
  checks: Array<{
    name: string;
    status: "pass" | "fail" | "warn" | "skip";
    message: string;
  }>;
  checked_at: string;
}

// mods.json
interface ModsState {
  loaded: string[];                  // Successfully loaded filenames
  failed: Array<{
    file: string;                    // JAR filename
    error: string;                   // Error description
  }>;
  total: number;
  loaded_count: number;
  failed_count: number;
  updated_at: string;
}

// update.json
interface UpdateState {
  status: "idle" | "checking" | "downloading" | "updating" | "failed";
  message: string;
  last_check: string | null;
  next_check: string | null;
  auto_update_enabled: boolean;
  updated_at: string;
}

Root → setup_user() → su-exec → hytale (PUID:PGID)

security_opt:
  - no-new-privileges:true

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro