RSS

What Is a Monorepo? Architecture, Benefits, and How to Scale Yours

Monorepos Infrastructure Terraform OpenTofu

Creating a monorepo is more than just a storage decision. It's an architectural decision that shapes how teams collaborate, automate, create, and ship. For infrastructure-as-code teams in particular, the efficiency of their monorepo can determine whether their pipeline moves fast or grinds to a halt.

TL;DR
$ cat what-is-a-monorepo.tldr
• A monorepo stores multiple projects or services in a single version-controlled repository, instead of splitting them across many separate repos.
• Monorepo architecture brings shared visibility, unified tooling, and easier cross-project refactoring, but introduces challenges around CI performance and access control at scale.
• Infrastructure-as-code teams face unique monorepo challenges, because every change carries real-world consequences and blast radius is more of a consideration.

Most developers have previously worked in a repository they outgrew. Sometimes it's a sprawling single repo that became slow and chaotic. Sometimes it's a constellation of separate repositories where frontend, backend, shared library, infrastructure code, and deployment scripts drift at different speeds, and one change causes a week of extra coordination.

Many teams decide to build a monorepo when that pain becomes obvious.

A monorepo stores multiple projects or services in a single version-controlled repository, rather than splitting them across multiple repositories, and can bring shared visibility, simplified dependency management, code sharing, easier refactoring, and better knowledge sharing.

However, deciding to use a monorepo also affects how teams manage dependencies, run automated tests, enforce repository boundaries, and reason about the entire codebase.

What is a monorepo?

A monorepo, sometimes called a monolithic repository, is a single repository that contains the source code for multiple projects, services, shared libraries, tools, or teams. The opposite model is a polyrepo, where each project has its own repository, usually with its own CI/CD pipeline, dependency management, permissions, and release process.

Mono refers to the repository, not the software architecture. A monorepo can contain a monolith, but it can also contain dozens of independently deployable services, libraries written in multiple programming languages, build tool configuration, test harnesses, and infrastructure code.

A monorepo setup might place:

Monorepos are common at serious levels of scale, and many will be familiar with the tooling behind them. For example:

Monorepo vs. polyrepo: a comparison

A polyrepo gives each project autonomy over its build system, permissions, dependency management, and quality assurance workflow. This model works well when projects have distinct compliance requirements, separate release schedules, or ownership boundaries that make shared source code inappropriate.

A monorepo centralizes the work. Related projects live in the same repo, so a change to a shared library and every dependent application can land in one commit, reviewers can see the full context, and teams can maintain consistency across formatting, test conventions, and build artifacts.

However, the negatives are easy to see: without affected-change detection, remote caching, incremental builds, and ownership policies, a monorepo can stop feeling collaborative and start feeling like a shared bottleneck, where every developer waits for unrelated projects to finish building.

Area Monorepo Polyrepo
Code location Multiple projects in one repository Each project is in its own repository
Collaboration Easier visibility and code sharing Stronger separation between teams
Dependency management Shared dependencies Dependencies managed per repo
CI/CD Unified pipelines that should run only what has changed Separate pipelines per repository
Access control Needs policies inside the same repository Permissions map to repository boundaries
Refactoring Atomic commits across multiple services Coordination across multiple repos
Best fit Related projects with mature tooling Unrelated projects or strict isolation needs

If you are choosing between a monorepo and a polyrepo, your decision should depend on how related your projects are, how often different teams change common code together, whether repository boundaries are a security requirement, and how mature your monorepo tools are.

There's also a middle ground: git submodules. A submodule keeps each project in its own separate repository, then references a specific commit of that repository from inside a parent repo, so you get something that looks like one checkout without actually merging any history together.

Git submodules are a good option when you need to vendor a specific version of someone else's code, or when a handful of teams want shared visibility without giving up their own release cadence, but it's not a monorepo in the main sense of the term.

Submodules still version everything individually, still fragment pull requests across repositories, and introduce their own friction, e.g., detached HEAD states, commit pointers that silently go stale, or a workflow most engineers only half remember until they need it.

Teams that decide to use submodules hoping to get monorepo-style visibility usually end up fighting the tool instead.

What is monorepo architecture?

Monorepo architecture is the internal shape of the repo, the conventions that determine where components reside, how sub-projects depend on each other, how the build system discovers work, and how teams prevent accidental coupling.

Some teams use a flat layout, where projects sit at the root.

Others group by team or domain, so payments, platform, data, and security have scoped directories that map to ownership.

Workspace-based layouts separate applications from packages and libraries (they're really two layers stacked on top of each other). Package manager workspaces (npm, pnpm, Yarn, and Bun, for instance) handle the mechanical work of linking local packages together without publishing them anywhere first.

On top of that sits an orchestration layer (Nx, Turborepo, and Bazel included) that builds a dependency graph of the whole repo, works out what a given change actually touches, and runs commands only against the affected projects.

A practical monorepo usually contains multiple applications and libraries in one Git repository, with tooling that makes shared code explicit, allows atomic changes across project boundaries, keeps dependencies consistent, runs commands only against affected projects, and uses remote caching so repeated work does not punish every developer.

A simple monorepo structure might look like this:

repo/
apps/
web/
api/
packages/
ui/
config/
libs/
core/
auth/
infra/
modules/
environments/
tools/
ci/

Code organization becomes policy, so the shape of the repository has to make ownership, dependencies, and shared boundaries obvious.

If apps/api imports private internals from apps/web, the monorepo structure is incorrect. A well-structured monorepo makes shared code explicit, keeps common code in a shared library, defines ownership at the directory or stack level, and lets CI answer only what changed and what depends on it.

The key characteristics of a well-structured monorepo

A healthy monorepo has consistent tooling across projects, a clear dependency graph between internal packages, shared linting and formatting standards, and CI that understands affected projects.

It also has social boundaries, so that ownership, review status, and team boundaries stay visible.

That distinction separates a monorepo from code colocation. Putting multiple services in the same repository is easy. Keeping large monorepos fast, understandable, and safe takes work.

The benefits of a monorepo

The biggest benefits of a monorepo become clear when a change crosses project boundaries.

In a polyrepo, updating an API type might require one pull request in the backend, another in the frontend, a version bump in a shared package, and careful sequencing so the main branch is never broken. In a monorepo, the same change can land atomically, with automated tests proving that affected projects still work.

Large-scale refactoring becomes more realistic, too. When the entire codebase is visible, teams can:

A monorepo also gives platform teams one place to encode best practices. Formatting, security scanning, task orchestration, build artifacts, quality assurance gates, and release workflows can be maintained consistently.

In mature setups, remote caching and incremental builds let work already completed on one developer's machine or CI runner be reused across multiple machines.

The challenges of a monorepo

Monorepos usually fail for the same reason. The repo grows, large files accumulate, every pull request triggers too much work, and CI/CD becomes the tax every developer pays for everyone else's code.

The main branch gets more fragile, and access control becomes harder because git repository permissions are usually blunt instruments.

That access-control issue is a big one. Most git repository permission models grant read access at the repository level, not the directory level, so putting everything in one place often means every engineer can read every other team's code by default, which is a least-privilege violation when it comes to security and compliance.

Versioning gets flattened too: many monorepos adopt a single version for the whole repo rather than semantic versioning per package, which works fine until a consumer needs to pin an old version of just one library and discovers there isn't a clean way to do it.

As they scale, monorepo tools start to become necessary rather than optional. A serious monorepo needs:

Large monorepos need branching models that respect scale, because full-repo branching can become expensive, while directory-level workflows can preserve team ownership without forcing every team to coordinate through the same release path.

Onboarding friction is another cost. New developers have to understand the monorepo structure, build system, local commands, ownership rules, and CI behavior before they can safely change code.

The best CI/CD setup for a monorepo runs only what changed

Ask ten engineers what the best CI/CD setup for a monorepo looks like, and nine of them will start with the same instinct: stop running everything on every pull request. A naive pipeline that rebuilds and retests the entire repo on every commit works fine at ten services but becomes a tax on everyone's afternoon at a hundred.

Affected-only pipelines are the approach that actually works across Nx, Turborepo, Bazel, and most serious in-house setups. They figure out which packages actually changed, identify the other packages that depend on them, and run builds and tests only against that subset. Everything else gets skipped, not because it's untested, but because nothing about it changed.

Independent builds and deployments per service are just as important as testing only what changed. If apps/api and apps/web are containerized and released separately, a backend fix doesn't have to wait behind an unrelated frontend change just because both live in the same repository. Remote caching keeps the pipeline fast by reusing work already completed on a developer's machine or by an earlier CI runner instead of repeating it. Together, these practices prevent build times from creeping upward as the monorepo grows.

Preview environments per pull request round out a mature setup. Spinning up an ephemeral environment that mirrors production for the lifetime of a single PR catches integration problems before merge, rather than after a dozen unrelated changes have already landed on top of them, and it pairs naturally with progressive delivery (blue-green or canary rollouts) once the change actually ships.

Terraform and OpenTofu workflows need the same affected-only discipline, but the shape is different: the pipeline isn't reasoning about which services changed; it's reasoning about which infrastructure stacks did, and what still depends on them. That's where Terraform automation and a working terraform ci/cd pipeline part ways with the application playbook above.

Monorepos and infrastructure as code

Monorepos get more dangerous when infrastructure as code enters the same repository. Terraform and OpenTofu configurations are often split across modules, environments, stacks, and shared components. Those components benefit from the same monorepo approach as application code, as modules can be reused, environment differences are visible, and infrastructure changes can be reviewed alongside the services they support.

However, IaC changes are not ordinary application changes. A broken unit test fails a build. A mistaken apply can change networking, destroy a database, rotate credentials, or modify production access.

The standard monorepo instinct of running everything on every pull request is slow for IaC, and can be expensive, noisy, and unsafe. It also raises the stakes on IaC security: the access-control problem mentioned above gets worse once the files everyone can read by default include provider credentials references and state backend configuration, not just application source.

The key concept to keep in mind is blast radius.

In a large IaC monorepo, a pull request that touches /infra/networking should not automatically plan every environment, every module, and every stack. It should identify the affected stacks, understand dependencies, run the right Terraform or OpenTofu plans, and show reviewers exactly what will change before anything is applied.

For IaC teams, the useful question is not whether a pull request changed infrastructure code, but which stacks it affects, what depends on those stacks, what order the work should run in, and what reviewers need to see before anything is applied.

Stategraph is built around that model, so Terraform and OpenTofu workflows can follow the infrastructure graph instead of treating the repository as one flat pile of files.

Why affected-change detection is important for IaC

Running terraform plan across every module on every PR looks thorough, but it burns CI minutes, creates review noise, and trains developers to ignore output because too much of it is unrelated. A better method is to understand the infrastructure graph well enough to run only what is affected, then run those plans in the right order.

General-purpose monorepo tools, and most infrastructure as code tools built for linting or provisioning rather than orchestration, are good with application dependency graphs, package builds, and test selection. Most do not understand Terraform state, OpenTofu workflows, workspace boundaries, module references, provider behavior, or the operational meaning of an apply.

IaC needs monorepo intelligence, but it also needs infrastructure intelligence.

Managing a monorepo at scale with Stategraph

Stategraph is built to help teams manage Terraform and OpenTofu workflows inside large repositories where speed, reviewability, and safety have to coexist. You can easily understand which stacks are affected by a change, how those stacks depend on each other, and which operations can safely run concurrently.

The naive alternative is either over-execution or under-protection. Stategraph is built around graph-aware execution, resource-level locking, multi-state operations, and blast radius analysis because an IaC monorepo needs more than just file-change detection – it needs to understand the infrastructure graph, especially when one repository contains many environments, stacks, and teams.

Large IaC monorepos contain shared modules, layered dependencies, team ownership boundaries, and apply rules that differ by environment. Stategraph handles that with tag-based configuration, stack-level access control, smart locking, layered runs, and module indexing, so changes trigger the right infrastructure workflows instead of turning every pull request into a full-repo event.

Stategraph keeps large IaC monorepos safe by locking only the stacks that need locking, showing reviewers the exact plan in the PR, and giving teams stack-level ownership without opening up the entire repository.

A monorepo can merely store infrastructure, or it can safely operate it. The first version is a storage decision. The second is an architectural choice backed by tooling that understands the consequences of code changes.

Conclusion

A monorepo is a single repo containing multiple projects, but the value comes from the workflow around it.

Good monorepo architecture:

For application teams, that usually means better code sharing, easier refactoring, simplified dependency management, and improved collaboration across services. For infrastructure-as-code teams, it also means blast radius control, safe plans, ordered applies, and policies that reflect the fact that code can change real infrastructure.

If your team is exploring one repository for apps, modules, environments, and shared infrastructure, ask yourselves if your tooling can keep the monorepo accurate as it grows.

Try Stategraph free to see how graph-aware Terraform and OpenTofu workflows keep a monorepo fast, reviewable, and safe when it becomes your production control plane.

Monorepo FAQs

What is the difference between a monorepo and a monolith?

A monorepo is a repository strategy. A monolith is an application architecture. A monorepo can contain many independently deployed services, while a monolith is usually one application deployed as one unit.

Is a monorepo good for small teams?

Yes, when the projects are related and the team benefits from code sharing, shared dependencies, and one CI/CD workflow. For unrelated projects, separate repositories may stay simpler.

When should a team adopt a monorepo?

The signal to watch for is how often changes cross project boundaries. If updating a shared library routinely means coordinating pull requests across several repositories just to land one logical change, and the team already has, or is willing to build, affected-change detection and caching, a monorepo usually pays for itself. If projects rarely share code, have genuinely different release cadences, or need hard security boundaries between teams, the coordination tax of a monorepo isn't giving much back, and separate repositories (or submodules, for the narrower vendoring case) are the simpler choice.

What tools are used to manage monorepos?

Common monorepo tools include Nx, Turborepo, Bazel, Yarn Workspaces, pnpm, and language-specific build systems. IaC teams also need Stategraph for Terraform and OpenTofu behavior.

How do you handle CI performance in a large monorepo?

Use affected-change detection, incremental builds, remote caching, task orchestration, and clear dependency rules. The goal is to run only what a change can affect.

What is monorepo architecture in the context of infrastructure as code?

In IaC, a monorepo is the structure of modules, environments, stacks, shared components, and policies inside the same repository, plus the workflow that maps a change to the exact plans and applies it affects.