Skip to content

ADR 0001: Monorepo Structure

Status: Accepted Date: 2026-04-29

Context

SCALR needs a central code home for the marketing website, login portal, application hub, internal tools, subscription products, and per-client work. These pieces must share authentication, design system, and API conventions. The team is currently small (one person) and operates on a single Proxmox server.

The two viable shapes are: - Monorepo — everything in one repository. - Polyrepo — one repository per app, with shared code published as packages.

Decision

Use a monorepo with a top-level layout that separates concerns:

  • apps/ — runnable user-facing applications (website, portal, admin, products).
  • clients/ — client-specific deployments (placement still open — see open-questions).
  • services/ — shared platform services (auth, gateway, billing, notifications, audit).
  • packages/ — shared libraries with no runtime of their own (auth SDKs, UI, types, utils).
  • template-app/ — the canonical starter app for new applications.
  • infra/ — Dockerfiles, compose files, scripts.
  • docs/ — MkDocs documentation site.
  • schemas/ — JSON schemas for repo-wide contracts (e.g. app manifest).

Consequences

Positive: - One clone, one CI config, one place to refactor cross-cutting changes. - Shared code lives next to its consumers — no publish step for internal libraries. - Easier to enforce repo-wide conventions (linting, testing, security scanning). - Search works across the whole platform.

Negative: - All code is visible to anyone with repo access. If client work needs confidentiality, that's an open question (see open-questions.md). - CI must be smart enough to build only affected parts at scale. Not yet a problem. - Single git log becomes very busy. Acceptable.

Alternatives considered

  • Polyrepo with private package registry. Rejected for now — too much process overhead for a one-person team. Easy to migrate to later if confidentiality forces it.