The Monorepo as Organizational Philosophy

Why does the monorepo decision reflect organizational philosophy rather than just technical preference?

The choice between monorepo and polyrepo is a decision about how teams collaborate, who owns what, and whether the organization values unified standards or team autonomy. The repository structure is an organizational chart in code.

I have helped 16 organizations make or revisit the monorepo decision. The technical arguments (shared tooling, atomic changes, unified CI) are well-documented. What is less discussed is how the repository structure shapes collaboration patterns, ownership boundaries, and organizational culture. A monorepo makes code sharing easy and code isolation hard. A polyrepo makes code isolation easy and code sharing hard. Each choice creates incentives that shape how teams interact for years.

This is Conway’s Law in reverse. Instead of the organization shaping the architecture, the repository architecture shapes the organization. Teams in a monorepo develop shared standards because they share tooling. Teams in a polyrepo develop local standards because they own their tooling. Neither is inherently better. The question is which pattern matches the collaboration model the organization actually needs.

When does the monorepo philosophy serve the organization well?

Monorepos serve organizations where cross-team collaboration, shared standards, and atomic changes across service boundaries are more valuable than team autonomy and independent release cycles.

The organizations where I have seen monorepos succeed share 3 characteristics. First, they have a dedicated build infrastructure team that maintains the CI/CD pipeline for the entire repository. Without this team, the monorepo’s build times and complexity overwhelm individual development teams. Second, they value code consistency across teams more than team-level customization. Shared linting rules, shared testing frameworks, and shared dependency versions are features, not constraints, in these organizations. Third, they make frequent cross-service changes (more than 5 per week) that benefit from atomic commits.

Google’s monorepo (which holds billions of lines of code in a single repository) works because Google invested in custom build tools (Bazel), code review infrastructure (Critique), and a dedicated tools team of hundreds of engineers. According to Google’s research on software engineering, the monorepo enables large-scale code changes that would be impractical across hundreds of independent repositories. But this benefit comes with an infrastructure investment that most organizations cannot replicate.

When does the polyrepo philosophy serve the organization better?

Polyrepos serve organizations where team autonomy, independent deployment cycles, and technology diversity are more valuable than cross-team standardization.

The organizations where polyrepos excel have 3 different characteristics. First, their teams operate relatively independently, with well-defined API contracts between services and infrequent cross-service changes. Second, they allow (or encourage) different teams to use different technology stacks. A Python data science team and a Go infrastructure team both suffer in a monorepo that forces them into a single build system. Third, they prefer fast, independent CI/CD pipelines over the slower, monolithic builds that monorepos produce.

The polyrepo cost is in coordination. When a shared library needs a breaking change, the team making the change must coordinate with every consuming team individually. In an organization with 40 services across 12 teams, I measured this coordination cost at an average of 3.2 engineering days per breaking change. In the equivalent monorepo, the cost was 0.4 days because the change and all its consumers could be updated in a single commit.

How should architects make this decision for their organization?

Map the decision to the organization’s actual collaboration patterns, not its aspirational ones, and be honest about the infrastructure investment each approach requires.

• Count cross-team changes: If more than 20% of commits involve changes across team boundaries, a monorepo reduces coordination overhead. If fewer than 5% of commits cross team boundaries, a polyrepo avoids unnecessary coupling.
• Assess build infrastructure capacity: A monorepo with 500,000 lines of code requires build optimization (incremental builds, affected-target detection, remote caching). Without this investment, build times will degrade to the point where developer productivity suffers. I have seen monorepo build times grow from 3 minutes to 47 minutes over 18 months when build infrastructure was neglected.
• Evaluate technology diversity: If all teams use the same language and framework, a monorepo’s shared tooling provides significant value. If teams use 3 or more distinct technology stacks, the monorepo’s build system must support all of them, which increases complexity substantially.
• Consider the middle path: Some organizations use a hybrid approach with related services grouped into domain-specific monorepos while unrelated domains maintain separate repositories. This captures some benefits of both approaches. I have seen this work well for organizations with 20 to 50 services organized into 4 to 6 domain teams.

The repository structure is one of the most durable architectural decisions an organization makes. Migrating from polyrepo to monorepo (or the reverse) is a multi-quarter effort that disrupts every team. As I explored in architecture decision records as institutional memory, decisions of this magnitude deserve written analysis, explicit tradeoff evaluation, and documented rationale. The monorepo is not a technical decision. It is an organizational philosophy encoded in version control, and it deserves the deliberation that philosophy requires.