The Misunderstood Monorepo: Architectural Trade-offs Teams Discover Only After They Commit
The monorepo debate tends to get framed as a technical decision, but it rarely is one. Whether a single repository helps or hurts has far less to do with git internals and far more to do with how a company is organized, how much it’s willing to invest in tooling, and how many teams are about to start stepping on each other’s toes. Teams that treat the choice as purely technical are usually the ones surprised, a year later, by the cost they didn’t see coming.
What a Monorepo Actually Solves
The genuine benefits of a monorepo are real, and they explain why companies like Google have stuck with the model at enormous scale. A single repository makes atomic cross-project changes possible: a shared library and every one of its callers can be updated in one commit, rather than coordinated across a dozen separate release cycles. Dependency versions stay unified by default, since there’s only one version of any internal library that anyone can depend on at a given moment. Large-scale refactors — renaming a widely used interface, upgrading a language runtime — become dramatically more tractable when every affected line of code lives in one place a tool can traverse.
Google’s own account of this trade-off, published as “Why Google Stores Billions of Lines of Code in a Single Repository”, remains one of the clearest first-hand descriptions of why this model can work — and how much custom tooling it took to make it work.
What It Silently Introduces
None of those benefits are free, and the costs tend to arrive later than the benefits do. Build and test times grow with the size of the repository unless a team invests early in tools built specifically for incremental, dependency-aware builds. Continuous integration queues become a shared resource that every team competes for, so a slow or flaky test suite in one part of the codebase can quietly delay releases for teams that never touched that code. Access control also gets coarser by default — restricting who can see or modify a specific service becomes harder in a single repository than it is when that service simply lives in its own isolated repo.
Perhaps the least discussed cost is blast radius. A single bad commit in a monorepo has the structural opportunity to affect every team at once, simply because everyone is downstream of the same repository, even if very few of them are downstream of that particular change in practice.
| Dimension | Monorepo | Polyrepo |
|---|---|---|
| Cross-project atomic changes | Native and straightforward | Requires coordinated multi-repo releases |
| Dependency version consistency | Enforced by default | Drifts unless actively managed |
| Build/CI scaling | Requires dedicated incremental tooling | Scales naturally per repository |
| Access control granularity | Coarser by default | Fine-grained per repository |
| Blast radius of a bad change | Structurally larger | Naturally contained to one repo |
The Organizational Precondition Nobody Talks About
Conway’s Law is usually invoked to explain why software ends up mirroring the org chart that built it, but it applies just as directly to repository structure. A monorepo tends to thrive when there’s a centralized platform or developer-tooling team explicitly responsible for build performance, ownership boundaries, and CI health across the whole organization. Without that investment, a monorepo doesn’t remove coordination costs — it just relocates them from “which repo has the latest version” to “why is my three-line change waiting behind two thousand other people’s CI jobs.”
This is precisely why tools like Bazel, Nx, and Turborepo exist at all: they’re not optional conveniences, they’re the load-bearing infrastructure that makes a large monorepo survivable. Adopting the repository structure without budgeting for that tooling is where most of the horror stories actually originate.
When Monorepos Become a Maintenance Burden
A handful of recurring signals tend to show up right before a team concludes the monorepo isn’t working for them anymore: build times that keep climbing despite hardware upgrades, a CI queue that routinely makes unrelated teams wait on each other, ownership boundaries that have become so blurred that no one is confident who should review a given change, and a growing habit of avoiding refactors specifically because the blast radius feels too large to reason about. None of these are inherent flaws of the model — they’re symptoms of the required tooling and governance investment never being made in the first place.
A Practical Decision Framework
| Signal | Leans toward |
|---|---|
| Small number of tightly coupled teams sharing most code | Monorepo |
| Dedicated platform team can own build and CI tooling | Monorepo |
| Teams need strict, independent access control per project | Polyrepo |
| Services are genuinely independent with rare cross-cutting changes | Polyrepo |
| Large-scale, frequent cross-project refactors are common | Monorepo |
| No near-term budget for incremental build tooling | Polyrepo |
Before committing to a monorepo, ask:
- Who owns CI and build performance as a full-time responsibility, not a side task?
- What’s our plan for incremental builds and tests once the repository is too large to build from scratch every time?
- How will we enforce ownership boundaries without the natural isolation a separate repository provides?
- Are the teams that would share this repository actually collaborating closely, or just co-located by convenience?
- Have we budgeted for the tooling investment, not just the initial migration?
What We Learned
Monorepos genuinely solve real problems — atomic cross-project changes, unified dependency versions, and tractable large-scale refactors — but none of that comes for free. The costs show up as build times, CI contention, coarser access control, and a structurally larger blast radius for any single bad change, and they tend to surface only once the repository and the organization around it have both grown past the point where undoing the decision is easy. The deciding factor isn’t really the size of the codebase; it’s whether the organization is willing to fund the tooling and governance a monorepo requires before the pain starts, rather than after.
