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

pnpm workspaces provide fast, disk-efficient dependency sharing across TypeScript packages.
Turborepo caches build and test tasks with explicit dependency graphs.
NestJS + Fastify offers structured modules, validation, and OpenAPI for the API layer.
Next.js supports SSR/RSC, i18n, and a modern React UX without a proprietary UI kit.
Go for node-agent and edge-gateway: small static binaries, strong concurrency, suitable for systemd daemons on game nodes.
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

docs/architecture/overview.md
docs/operations/installation.md
docs/security/threat-model.md

2.8 KiB Raw Blame History