# 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`