initial commit

docs/adr/0001-monorepo-architecture.md

@@ -0,0 +1,70 @@
+# ADR 0001: Monorepo architecture
+
+- **Status:** Accepted
+- **Date:** 2026-06-26
+- **Deciders:** HexaHost GameCloud core team
+
+## Context
+
+HexaHost GameCloud is a multi-component platform: web UI, REST API, background workers, per-node Go agents, and a future edge gateway. Teams need shared contracts, consistent tooling, and atomic changes across services.
+
+## Decision
+
+Adopt a **pnpm + Turborepo monorepo** with the following application split:
+
+| Component | Technology | Responsibility |
+|-----------|------------|----------------|
+| `apps/web` | Next.js (App Router) | User and admin UI |
+| `apps/api` | NestJS + Fastify | REST API, auth, orchestration |
+| `apps/worker` | NestJS / Node | BullMQ jobs, scheduler |
+| `apps/node-agent` | Go | Game node daemon, container lifecycle |
+| `apps/edge-gateway` | Go | TCP/UDP Join-to-Start (Phase 8) |
+| `packages/*` | TypeScript | Shared database, contracts, UI, config |
+
+Supporting infrastructure:
+
+- **PostgreSQL** — primary data store (Prisma ORM)
+- **Redis** — cache, locks, BullMQ queues
+- **S3-compatible storage** — backups and large artifacts
+- **Docker Compose** — local and control-plane production deployment
+- **systemd** — node agent on game nodes
+- **Traefik** — TLS termination and routing (external)
+
+## Rationale
+
+1. **pnpm workspaces** provide fast, disk-efficient dependency sharing across TypeScript packages.
+2. **Turborepo** caches build and test tasks with explicit dependency graphs.
+3. **NestJS + Fastify** offers structured modules, validation, and OpenAPI for the API layer.
+4. **Next.js** supports SSR/RSC, i18n, and a modern React UX without a proprietary UI kit.
+5. **Go** for node-agent and edge-gateway: small static binaries, strong concurrency, suitable for systemd daemons on game nodes.
+6. **Prisma** gives type-safe schema evolution and migration tooling shared by API and worker.
+
+## Consequences
+
+### Positive
+
+- Single repository for cross-cutting changes (API contract + UI + worker).
+- Shared TypeScript types via `packages/contracts`.
+- Unified CI for all languages.
+- Clear deployment boundaries: Compose for control plane, systemd for agents.
+
+### Negative
+
+- Larger clone size and CI surface area.
+- Go modules live outside the Node dependency graph; versioning is manual.
+- Developers need Node 22, pnpm, Go 1.23, and Docker.
+
+## Alternatives considered
+
+| Alternative | Rejected because |
+|-------------|------------------|
+| Polyrepo | Harder to keep contracts and releases in sync |
+| Kubernetes | Explicitly out of MVP scope; Compose + VMs first |
+| Single language (all TypeScript) | Go better fits low-level node agent requirements |
+| tRPC only (no REST) | REST + OpenAPI required for WHMCS integration and public API docs |
+
+## Related documents
+
+- `docs/architecture/overview.md`
+- `docs/operations/installation.md`
+- `docs/security/threat-model.md`