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.

Next

• 02-ssot-where