# Architecture overview

HexaHost GameCloud is a self-hosted, multi-tenant platform for on-demand Minecraft servers.

## High-level diagram

```mermaid
flowchart TB
    subgraph users [Users]
        Browser[Web Browser]
        MC[Minecraft Client]
    end

    subgraph control [Control Plane]
        Web[Next.js Web]
        API[NestJS API]
        Worker[BullMQ Worker]
        PG[(PostgreSQL)]
        Redis[(Redis)]
        S3[(S3 / MinIO)]
    end

    subgraph nodes [Game Nodes]
        Agent[Go Node Agent]
        Docker[Docker Engine]
        Server[Minecraft Containers]
    end

    subgraph future [Phase 8+]
        Edge[Edge Gateway]
    end

    Browser --> Web
    Web --> API
    API --> PG
    API --> Redis
    Worker --> Redis
    Worker --> PG
    Worker --> S3
    API <-->|mTLS WebSocket| Agent
    Agent --> Docker
    Docker --> Server
    MC --> Server
    MC -.-> Edge
    Edge -.-> API
```

## Component responsibilities

### Control plane

Runs on one or more VMs (Ubuntu 24.04 / Debian 13). Handles authentication, server metadata, scheduling decisions, billing projection, and job orchestration. **Never** mounts the Docker socket.

### Game nodes

Dedicated Linux VMs with Docker Engine (cgroup v2). Each node runs the **node-agent** as a systemd service. The agent connects **outbound** to the API via mTLS WebSocket and executes signed lifecycle commands locally.

### Data flow

1. User creates a server via the web UI.
2. API persists state in PostgreSQL and enqueues provisioning jobs.
3. Worker selects a node, reserves resources, and sends `server.provision` to the agent.
4. Agent creates an isolated container and reports `server.state` transitions.
5. Backups stream to S3; metadata stays in PostgreSQL.

### Security boundaries

| Boundary | Mechanism |
|----------|-----------|
| User → API | HTTPS, session cookies, CSRF, rate limits |
| API → Agent | mTLS, node token, signed JSON messages |
| Agent → Docker | Local Unix socket only, no remote exposure |
| Game container → Internet | Egress rules, no internal network access by default |

## Repository layout

See [ADR 0001](../adr/0001-monorepo-architecture.md) for the full monorepo structure.

## Protocol

Agent communication uses versioned JSON envelopes over WebSocket. Message types include `agent.hello`, `agent.heartbeat`, `server.start`, and `server.state`. See `apps/node-agent/internal/protocol/messages.go`.

## Deployment models

| Environment | Mechanism |
|-------------|-----------|
| Local development | `deploy/compose/compose.dev.yml` |
| Production control plane | Docker Compose + Traefik |
| Game nodes | Ansible + systemd node-agent |

## Phase roadmap

| Phase | Focus |
|-------|-------|
| 0 | Repository, infra, CI, docs |
| 1 | Authentication |
| 2 | Single-node vertical slice |
| 3–7 | Panel features, multi-node, idle shutdown |
| 8 | DNS, edge gateway, join-to-start |
| 9 | Billing, production hardening |