The monorepo vs microservices debate usually centers on build performance, deployment independence, and team autonomy. These are valid concerns. But there's a dimension that nobody discusses: knowledge management.
Monorepo Knowledge Properties
In a monorepo, all code is in one place. This means:
- Full text search works. grep finds everything.
- Dependency chains are visible. You can trace imports from UI to database in one repository.
- Refactoring is atomic. Rename a function and update all callers in one PR.
- Onboarding scope is clear. There's one repo to understand (even if it's huge).
The downside: the knowledge surface area is enormous. A monorepo with 500K lines of code is too large for any individual to understand completely. Developers develop deep expertise in their area and shallow familiarity with the rest.
Microservices Knowledge Properties
In a microservices architecture, code is distributed across 10-50+ repositories. This means:
- Search is fragmented. grep only covers one repo at a time.
- Dependencies cross repository boundaries. Service A calls Service B's API, but you can't trace the implementation without switching repos.
- Refactoring is multi-step. Changing an API requires coordinating changes across 2-3 repos.
- Onboarding is scoped but incomplete. New developers understand their service but not the system.
The knowledge cost: every cross-service interaction requires a developer to understand two or more codebases, their contracts, and their implicit assumptions.
The Knowledge Tax Comparison
For a complex, cross-cutting feature:
Monorepo: Developer traces the full implementation in one repo. Understanding Tax: 30-60 minutes. Can see all affected code in one PR.
Microservices: Developer traces implementation across 3 repos. Must understand 3 different codebases, 3 API contracts, and 3 deployment pipelines. Understanding Tax: 2-4 hours. Changes require 3 coordinated PRs.
The microservices approach trades individual service simplicity for system-level complexity. For cross-cutting work, the knowledge overhead is 3-5x higher.
How Code Intelligence Changes the Equation
Code intelligence tools can bridge the microservices knowledge gap:
- Cross-repo dependency graphs that trace calls across service boundaries
- Unified search across all repositories
- Feature maps that group files from multiple repos into logical features
- Impact analysis that shows cross-service blast radius
With these tools, the knowledge properties of microservices approach those of a monorepo — you get the deployment independence of microservices with the discoverability of a monorepo.
The architecture decision shouldn't be about which is "better." It should be about which knowledge properties your team can support — and whether tools can compensate for the gaps.
Originally published on glue.tools. Glue is the pre-code intelligence platform — paste a ticket, get a battle plan.
Top comments (0)