initial commit

docs/architecture/overview.md

@@ -0,0 +1,100 @@
+# 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 |