Monorepo vs. Polyrepo — The Decision Framework Nobody Gives You

The Holy War

Monorepo advocates say: "Google uses a monorepo!" Polyrepo advocates say: "Amazon uses microservices with separate repos!" Both are right. Both are wrong. Because neither answer applies to your 20-person engineering team.

The right repository strategy depends on three things: team structure, deployment coupling, and code sharing patterns. Not what Google does.

The Decision Matrix

Choose MONOREPO when:
  ✓ Teams share significant code (types, utilities, components)
  ✓ Services need to deploy together frequently
  ✓ You have < 50 engineers (tooling overhead is manageable)
  ✓ You want atomic cross-project changes
  ✓ Your CI/CD can handle selective builds

Choose POLYREPO when:
  ✓ Teams are fully autonomous and rarely share code
  ✓ Services deploy completely independently
  ✓ You have > 100 engineers (monorepo tooling becomes expensive)
  ✓ Teams use different languages/frameworks
  ✓ You need strict access control between projects

Choose HYBRID when (most common for 20-80 engineers):
  ✓ Group related services in monorepos by domain
  ✓ Keep truly independent services in their own repos
  Example: frontend-monorepo, backend-monorepo, infra-repo, data-repo

Monorepo: The Real Trade-offs

What monorepo advocates don't tell you:

CI gets complex fast. If every commit triggers builds for every project, your CI bill explodes and feedback loops slow down:

# Turborepo/Nx filter: only build what changed
# turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    }
  }
}
 
# Only build affected packages
# npx turbo run build --filter=...[HEAD~1]

Without affected-project detection (Turborepo, Nx, Bazel), a monorepo is just a slow polyrepo in a trench coat.

Git performance degrades. Large monorepos slow down git status, git log, and git blame:

# Mitigations for large monorepos
git config core.fsmonitor true          # File system monitor (faster status)
git config core.untrackedCache true     # Cache untracked files
git sparse-checkout set packages/my-app # Only check out what you need

Code ownership gets blurry. Without explicit ownership, shared code becomes nobody's responsibility:

# CODEOWNERS file is critical in a monorepo
# .github/CODEOWNERS
/packages/api/        @backend-team
/packages/web/        @frontend-team
/packages/shared/     @platform-team
/infra/               @devops-team

What polyrepo advocates don't tell you:

Dependency management is a nightmare. When package-A depends on package-B, every update requires a version bump, publish, and update cycle:

Polyrepo dependency update:
  1. Fix bug in shared-utils
  2. Bump version, publish to npm
  3. Update shared-utils in service-A → PR → merge → deploy
  4. Update shared-utils in service-B → PR → merge → deploy
  5. Update shared-utils in service-C → PR → merge → deploy
  Time: Hours to days

Monorepo dependency update:
  1. Fix bug in shared-utils
  2. All services automatically use the fixed version
  Time: Minutes

Cross-cutting changes require heroic coordination. Renaming a shared type across 8 repos means 8 PRs, 8 reviews, and careful ordering.

The Hybrid Approach (What Most Teams Should Do)

Group repos by deployment boundary and team ownership:

Repository structure for a 30-person e-commerce team:

storefront-monorepo/           (Frontend team, 8 engineers)
  ├── apps/web/                 Next.js storefront
  ├── apps/mobile/              React Native app
  ├── packages/ui/              Shared component library
  ├── packages/hooks/           Shared React hooks
  └── packages/types/           Shared TypeScript types

backend-monorepo/              (Backend team, 12 engineers)
  ├── services/api/             Main API service
  ├── services/orders/          Order processing service
  ├── services/inventory/       Inventory service
  ├── packages/db/              Shared database utilities
  └── packages/events/          Shared event types

infra-repo/                    (Platform team, 5 engineers)
  ├── terraform/                Infrastructure as code
  ├── k8s/                      Kubernetes manifests
  └── scripts/                  Deployment scripts

data-repo/                     (Data team, 5 engineers)
  ├── pipelines/                ETL pipelines
  ├── models/                   ML models
  └── dashboards/               Dashboard configs

This gives you the benefits of monorepo (shared code, atomic changes) within team boundaries, while keeping team repos independent where they don't need to share.

The Migration Path

If you're currently in many repos and want to consolidate:

Step 1: Identify the coupling
  → Which repos change together most often?
  → Which repos share code via published packages?
  → Which repos are owned by the same team?

Step 2: Group by affinity
  → Repos that change together → same monorepo
  → Repos with shared code → same monorepo
  → Repos with different teams and no coupling → keep separate

Step 3: Migrate incrementally
  → Start with the 2-3 most coupled repos
  → Use git subtree or git-filter-repo to preserve history
  → Set up Turborepo/Nx for affected builds
  → Migrate more repos as the tooling proves out

The right answer isn't monorepo or polyrepo. It's the repo structure that matches your team structure and deployment patterns. Conway's Law applies to repositories too — your repo boundaries will mirror your team boundaries whether you plan for it or not.