The monorepo mental model

Separate repository shape from deployment shape

A monorepo stores multiple applications and packages in one version-control repository. Those applications may deploy together or independently. A monolith can live in many repositories, and many microservices can live in one monorepo.

The repository gives atomic changes, shared tooling, discoverability, and a global dependency graph. It does not remove the need for API boundaries, ownership, release discipline, or service isolation.

Know which problem you are solving

• Change an application and its shared library atomically
• Standardise linting, testing, TypeScript, and build conventions
• Discover and refactor code across product boundaries
• Reuse components and domain packages deliberately
• Run only tasks affected by a change
• Make ownership and dependency direction visible

The costs arrive with scale

A naive checkout, install, test, and build of everything becomes slow. Broad permissions expose more code than some teams require. An unstable shared package can fan failures across many products.

The answer is not a larger CI machine alone. You need package boundaries, deterministic tasks, caching, affected-change calculation, ownership rules, and tooling that works locally and in CI.

Repository and deployment are different graphs

Choose deliberately

A monorepo fits when teams benefit from coordinated changes and can agree on a shared engineering platform. Multiple repositories may be better when access boundaries are strict, products are unrelated, or independent ecosystems make shared tooling artificial.

Repository strategy is reversible but expensive to change. Record the decision, expected benefits, and signals that would cause a reassessment.