Monorepo versus polyrepo generates more heat than most architecture debates and resolves less, because both sides are describing real experiences of different situations. The layout is downstream of a more useful question: how tightly coupled is your code, and how much cross-team coordination does a typical change require. Answer that and the repository structure follows.
01What a monorepo actually gives you
The defining benefit is the atomic cross-cutting change. Update a shared library and every consumer in one commit, one review, one merge. No version bump, no publish, no waiting for downstream teams to upgrade, no period where different services run incompatible versions of the same library.
This matters enormously when code is genuinely coupled. If a typical feature touches a shared component, two services and a client, doing that as one reviewable change is qualitatively better than coordinating four pull requests across four repositories with an ordering dependency between them.
02What it costs
Tooling. A monorepo past a certain size requires build tooling that understands the dependency graph, computes affected targets, and caches aggressively - because naively running everything on every change becomes untenable quickly. That is real, ongoing investment, and teams that adopt the structure without the tooling get the costs without the benefits.
It also concentrates risk. One repository means one CI system whose outage blocks everyone, one set of permissions that is harder to scope narrowly, and a repository large enough that clone and checkout times become a real friction for daily work.
| Dimension | Monorepo | Polyrepo |
|---|---|---|
| Cross-cutting changes | Single atomic commit | Coordinated across repos |
| Dependency versions | One version, always current | Independent, can drift badly |
| Build tooling | Required investment | Simple per repo |
| Team autonomy | Shared conventions dominate | High - each team decides |
| Access control | Coarse; needs extra tooling | Natural per-repo boundaries |
| Onboarding | Everything visible at once | Smaller, more approachable scope |
| CI blast radius | One failure affects all | Isolated per repo |
03The diamond dependency problem
Polyrepo's characteristic failure is version drift. Service A needs version 2 of a shared library, service B is pinned to version 1, and a security fix must be backported to both. Multiply across dozens of services and a meaningful fraction of engineering time goes to upgrade coordination that produces no customer value.
This is the strongest argument for a monorepo, and it strengthens as shared code increases. If your services share substantial internal libraries, polyrepo makes you pay for that sharing continuously. If services genuinely share nothing but network protocols, the problem never arises and the monorepo tooling investment buys little.
04Conway's law applies either way
Repository structure and team structure interact, and the mismatch is where friction lives. A monorepo with strong team ownership boundaries works well - directories map to teams, code owners enforce review, and autonomy is preserved within a shared structure.
A monorepo without ownership boundaries becomes a commons where nobody is responsible for shared code quality. Conversely, polyrepo with tightly coupled teams produces constant cross-repository coordination that a monorepo would have made trivial. Structure should follow how teams actually collaborate, not an abstract preference.
- Map directories to owning teams explicitly and enforce with code owners.
- In polyrepo, invest in dependency update automation from the start.
- Watch for repos that always change together - a consolidation signal.
- Watch for a monorepo directory nobody owns - an extraction signal.
05A pragmatic middle
Most organisations end up between the extremes, and that is a reasonable destination rather than a failure to decide. A monorepo for tightly coupled application code and shared libraries, separate repositories for genuinely independent systems - infrastructure definitions, machine learning pipelines, public SDKs with their own release cadence.
The decision is also reversible in one direction more easily than the other. Merging repositories is mechanical; splitting a monorepo where everything imports everything is genuinely hard. If uncertain and starting small, separate repositories with disciplined boundaries preserve more options.
Topics
Lena Voss
Lead Architect · SyncTrix
Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.
Building something like this?
SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.