101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
# 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 |
|