71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# 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`
|