Monorepo vs polyrepo

Past three projects, structural decisions matter more than any individual library pick.

1. Monorepo

warragon/
├── frontend/
│   ├── pryzeet/
│   ├── admin/
│   └── codingstairs/
├── backend/
│   ├── java-backend/
│   └── python-backend/
├── infra/
└── docs/

2. Pros

Atomic cross-repo changes
Shared utilities/types in one place
Unified tooling (pnpm · Docker · CI)
Easy refactors (search/replace across repo)
Team visibility

3. Cons

Large repo (GB+)
CI complexity (which project changed?)
Access control harder
Tooling locked (one Node version)

4. Polyrepo

Separate repos per project — pryzeet-web, pryzeet-api, admin-web …

5. Pros

Small repos
Access control per repo
Independent releases
Per-project tooling

6. Cons

Cross-repo changes require multiple PRs
Code duplication
Version drift
Poor discoverability

7. How to choose

Situation	Pick
Solo / small team	monorepo
Tightly coupled frontend + API	monorepo
100+ engineers	polyrepo or Nx/Turborepo monorepo
Strict access separation	polyrepo
Library publishing	polyrepo (semver)

8. Tools

pnpm workspaces · Nx · Turborepo · Lerna.

# pnpm-workspace.yaml
packages:
  - "frontend/*"
  - "backend/*"
  - "packages/*"

pnpm -F pryzeet add lodash
pnpm -F "./frontend/*" typecheck

9. CI optimisation

- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      frontend_pryzeet: frontend/pryzeet/**

- if: steps.changes.outputs.frontend_pryzeet == 'true'
  run: cd frontend/pryzeet && pnpm test

Turborepo handles cache + dep graph automatically.

10. Coupling discipline

Being in one repo doesn't grant cross-import rights. Enforce with eslint-plugin-boundaries.

11. Our monorepo (warragon)

9 services (7 frontends + 2 backends), 5 PostgreSQL instances, 3 Docker environments, one docs/ SSOT. Atomic PRs and unified Claude agent setup are the wins.

12. Gotchas

Half-pushed changes
Workspace dependency loops
Over-splitting into 100 tiny packages
External contributors / sensitive modules — use separate repo or CODEOWNERS

Closing

"Polyrepo from day one" is a common mistake. Start monorepo, split later when scale or access control demands.

02-ssot-where