What is monolith team ownership, and how do you know you have an ownership problem?

Monolith team ownership means assigning business modules, such as billing, search, or identity, to teams that are accountable for them. Those teams own design decisions, review, and incidents for that module. File permissions are only a mechanism for this. The unit being assigned is a capability with a boundary, not a list of paths. Organizations adopt it when several teams share one codebase and "everyone owns it" has turned into "nobody owns it." Reviews drag because no one feels entitled to say no. Incidents bounce between channels. Every change needs a meeting.

Diagnose before you reorganize

Look for these symptoms:

  • Many unrelated committers on the same files. The module has no real boundary.
  • PRs that routinely need sign-off from three or more teams. The coupling is structural, not occasional.
  • Incidents that sit unclaimed while people work out whose code failed.
  • Directories touched by nearly every change. These are usually shared utilities or a "common" package absorbing logic that belongs elsewhere.

Measure who actually changes what, because the org chart describes intent, not behavior. Run git shortlog -sn --since="6 months ago" HEAD -- src/billing/ to rank contributors to a path. Include HEAD explicitly, because without a revision git shortlog reads from standard input when it isn't run in a terminal, such as in scripts. Use git log --since="6 months ago" --format= --name-only HEAD | sort | uniq -c | sort -rn to find the most frequently changed files. Map authors to teams and compare the result with who you think owns each area. The mismatches tell you where to draw boundaries first.

#!/usr/bin/env bash
# Map who actually changes what, before touching CODEOWNERS or the org chart.
# Run from the repository root. Placeholder module paths; replace with yours.
set -eu

SINCE="${SINCE:-6 months ago}"
MODULES=(src/billing src/search src/identity src/common)

echo "== Top contributors per module =="
for path in "${MODULES[@]}"; do
  echo "-- $path"
  # HEAD is explicit so shortlog reads history, not stdin, in scripts and CI.
  git shortlog -sn --since="$SINCE" HEAD -- "$path" | head -n 10
done

echo
echo "== Most frequently changed files (hotspots) =="
# --format= drops the commit header, leaving only file names per commit.
git log --since="$SINCE" --format= --name-only HEAD \
  | sed '/^$/d' | sort | uniq -c | sort -rn | head -n 20

echo
echo "== Distinct authors per directory (high count = weak boundary) =="
# Emit '@author' lines followed by changed files, then pair each file's
# two-level directory with its author and count unique authors per directory.
git log --since="$SINCE" --format='@%ae' --name-only HEAD \
  | awk '/^@/ { author = substr($0, 2); next }
         NF  { n = split($0, p, "/");
               dir = (n > 2) ? p[1] "/" p[2] : p[1];
               print dir "\t" author }' \
  | sort -u | cut -f1 | uniq -c | sort -rn | head -n 20

# Next step (manual): map author emails to teams and compare against
# who you believe owns each module. Mismatches show where to draw boundaries.

A read-only bash script that uses git shortlog and git log filtered by path to rank contributors per module, find hotspot files, and count distinct authors per directory so you can compare actual change patterns with assumed ownership.

How should you draw module boundaries in a monolith?

Draw boundaries around business capabilities such as billing, catalog, or fulfilment, not around technical layers. If one team owns controllers, another owns services, and a third owns repositories, every feature touches all three. A new refund rule needs an endpoint, domain logic, and a query, so it needs three reviews and three backlogs, and nobody owns the outcome.

Layer-sliced                     Capability-sliced
+-----------------------+        +---------+---------+---------+
| Controllers  (Team A) |        | Billing | Catalog | Orders  |
+-----------------------+        |  API    |  API    |  API    |
| Services     (Team B) |        |  logic  |  logic  |  logic  |
+-----------------------+        |  data   |  data   |  data   |
| Repositories (Team C) |        | (Team A)| (Team B)| (Team C)|
+-----------------------+        +---------+---------+---------+
 every feature crosses            most features stay
 all three teams                  inside one team

To find the seams, use two signals:

  • Change coupling. Files that change together in the same commits belong in the same module. If invoice.rb and tax_rules.rb almost always appear in the same commit, splitting them between owners creates constant cross-team coordination.
  • Data ownership. Group code by the tables it writes. A module should be the only writer of its tables. Other modules read through its interface.

Do not copy the current org chart. Conway's Law says systems mirror the communication structure of the organization that builds them. Deliberately cutting code to fit today's teams runs that process in reverse and locks in whatever cohesion problems the org already has. Draw the modules first, then assign teams to them.

Aspect Layer-sliced Capability-sliced
Teams touched per feature Usually all Usually one
Cohesion Low High
Data ownership Shared One writer per table
Review bottlenecks Every change Only at interfaces
Survives reorgs Poorly Reassign whole modules
LAYER-SLICED                              CAPABILITY-SLICED

    [refund rule]                                  [refund rule]
          |                                              |
          v                                              v
  +--------------+                        +----------------------------+
  | Controllers  |  Team A: review 1      | Billing           (Team A) |
  +--------------+                        |  API:   refund endpoint    |
          |                               |  logic: refund rule        |
          v                               |  data:  refunds table      |
  +--------------+                        +----------------------------+
  | Services     |  Team B: review 2        one team, one review
  +--------------+
          |
          v
  +--------------+
  | Repositories |  Team C: review 3
  +--------------+
  3 teams, 3 backlogs, no single owner

DATA OWNERSHIP: one writer per table; others read via its interface

  +-----------------+  reads via    +------------------+
  | Orders (Team C) |-------------->| Billing (Team A) |
  +-----------------+  interface    +------------------+
                                              | sole writer
                                              v
                                 [invoices, refunds tables]

In a layer-sliced monolith, one refund-rule change needs three teams and three reviews. In a capability-sliced monolith, the same change stays inside the Billing module, which is the only writer of its tables, and other modules read that data through Billing's interface.

How does a CODEOWNERS file work, and how should you structure it?

A CODEOWNERS file maps path patterns to owners. When a pull request touches a file, the platform finds the patterns that match that path and requests review from the listed owners. On most platforms the last matching pattern wins, so order matters. Put broad rules first and specific rules after them. If you reverse that order, a catch-all at the bottom silently overrides every module rule above it.

On its own the file only routes review requests. It becomes a control when you combine it with branch protection that requires code owner approval on the main branch. A change to a module then cannot merge until someone from the owning team approves it.

The accompanying example follows three rules:

  • Mirror module directories. Each top-level module path, such as the billing, catalog, and identity packages, gets one line and one owning team. If someone has to read the file to learn where a module's boundary is, the boundary is not real yet.
  • Use team handles, not individuals. Team membership changes in your identity system without anyone editing the file. Reviews also don't stall because one person is on leave.
  • Keep a fallback owner for unmatched paths. A catch-all line at the top assigns everything else, such as build scripts and new directories, to a platform or architecture group. This keeps every file owned while new code waits for a proper home.

The file should follow the module layout, not define it. Draw the boundaries in the code first, then write CODEOWNERS to describe them.

# CODEOWNERS: describes module boundaries that already exist in the code.
# Later lines override earlier ones on most platforms, so the order is:
# broad fallback first, specific modules after.

# Fallback owner for anything not matched below: build scripts,
# top-level config, and new directories that have no module home yet.
*                           @example-org/platform-architecture

# One line per module directory, one owning team per module.
# Team handles, not individuals, so ownership survives staffing changes.
/src/modules/billing/       @example-org/billing-team
/src/modules/catalog/       @example-org/catalog-team
/src/modules/identity/      @example-org/identity-team

# Shared contracts between modules: changes affect every consumer,
# so route them to the architecture group as well as the module owner.
/src/modules/billing/api/   @example-org/billing-team @example-org/platform-architecture

# Do NOT add a catch-all '*' line down here: as the last match it
# would override every module rule above it.

A CODEOWNERS file that mirrors module directories, assigns each to a team handle, and keeps a fallback owner on the first line so the more specific module rules after it take precedence.

How do you enforce module boundaries in code and CI?

A boundary that exists only in a diagram will erode within a few sprints, because the shortest path to shipping a feature is usually a direct call into another module's internals. Make the correct path the only path that compiles.

Give each module one public surface: a top-level package, namespace, or facade that exposes the operations other teams may call. Mark everything else internal with the language's own visibility features, such as package-private classes in Java, internal in C#, or an internal/ directory in Go. The compiler then enforces the boundary for free, and the facade becomes the explicit contract the owning team reviews.

Visibility rarely covers module-to-module rules, so add an architecture check in CI. The rule can be a small table: billing may depend on accounts.api, and nothing may depend on billing.internal. The check script walks each source file, extracts its imports, maps each file and each import to a module, and fails the build on any pair the table does not allow. It is crude, but it is fast and readable, and a failed build forces the conversation before merge rather than after.

Teams will route around the check, usually under deadline pressure:

  • Reflection and string-based lookups that load classes or services by name. Flag reflection APIs and string literals that match internal paths.
  • Dependency injection configuration that wires an internal implementation into another module. Scan container config as well as source code.
  • A growing allowlist. Require an owner and an expiry date on every entry, and report the total count so that growth is visible.
import pathlib, re, sys

# Dependency rule: each module may import only these public surfaces of other modules.
# Anything not listed, including every *.internal package, is forbidden.
ALLOWED = {
    "billing": {"accounts.api"},
    "accounts": set(),
    "reports": {"billing.api", "accounts.api"},
}
IMPORT_RE = re.compile(r"^\s*(?:from|import)\s+([\w.]+)", re.M)
# Catch bypasses: class or service names passed as strings to reflection or DI config.
INTERNAL_STR_RE = re.compile(r"[\"']([A-Za-z_]+\.internal[\w.]*)[\"']")

def allowed(src_mod, target):
    top = target.split(".")[0]
    if top == src_mod or top not in ALLOWED:
        return True  # same module, stdlib, or third-party
    return any(target == a or target.startswith(a + ".") for a in ALLOWED[src_mod])

def main(root):
    errors = []
    for path in pathlib.Path(root).rglob("*.py"):
        src_mod = path.relative_to(root).parts[0]  # src/<module>/...
        if src_mod not in ALLOWED:
            continue
        text = path.read_text(encoding="utf-8")
        for target in IMPORT_RE.findall(text):
            if not allowed(src_mod, target):
                errors.append(f"{path}: {src_mod} may not import {target}")
        for target in INTERNAL_STR_RE.findall(text):
            if target.split(".")[0] != src_mod:
                errors.append(f"{path}: string reference to {target}")
    print("\n".join(errors) or "module boundaries OK")
    return 1 if errors else 0  # non-zero exit fails the CI job

if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "src"))

A minimal CI check that maps each file and import to a module, fails the build on any dependency the rule table does not allow, and flags string literals that name another module's internals, a common reflection or DI bypass.

Who owns shared code, the database, and on-call in a modular monolith?

Team Topologies gives a workable map. Stream-aligned teams own business modules end to end: code, tables, alerts, and the decision to change them. A platform team owns build, CI, deployment, and the shared runtime. Enabling teams own nothing permanent. They help others adopt boundaries and then step back.

Team type Owns Default interaction mode
Stream-aligned Business modules, their tables, alerts, tests X-as-a-service with other modules
Platform Build, CI, deploy pipeline, shared runtime, shared libraries X-as-a-service
Enabling No modules; temporary guidance Facilitating

The interaction mode tells you how to change code you don't own. The default is X-as-a-service: you open a request or a small pull request against the module's public interface, and the owner decides. Use collaboration, meaning a time-boxed joint effort, only when two teams are reshaping a boundary together. Agree on an end date so it doesn't become shared ownership by default.

Keep shared code like auth, logging, and persistence helpers small. Every addition becomes a dependency for every team. Give it a named owner, require a design note for new APIs, and reject business logic.

Assign every database table to exactly one module. Other modules read through that module's interface, not with direct queries. Shared tables are where boundaries quietly fail, because no one is accountable when a schema change breaks a hidden reader.

Ownership goes beyond code review. The owner is also accountable for:

  • alert routing
  • dependency upgrades
  • fixing or quarantining flaky tests
  • running deprecations to completion

How do you migrate to module ownership incrementally and keep it current?

Stage the rollout

Roll out enforcement in three steps, so teams can adjust before anything blocks a merge.

  1. Metadata and advisory reviews. Add ownership metadata and let it auto-request reviewers, but do not require their approval. For a few weeks you learn which boundaries cause friction, and nobody's merge is blocked by a guess.
  2. Architecture tests in warning mode. Run the boundary checks on every pull request and report violations without failing the build. This exposes the real dependency graph, which is often messier than the diagram.
  3. Blocking, one module at a time. Turn on enforcement for the module with the clearest boundary and the most willing owner. Then expand. A single global switch tends to produce a pile of exemptions on the first day.

Track violations with a shrinking allowlist

Record every existing violation in an allowlist file checked into the repo. Each entry names the source module, the target module, and the owning team. CI then enforces two rules:

  • Any violation not on the list fails the build.
  • The list may not grow.

Progress becomes visible as the diff on that file, and new violations can't hide among the old ones.

Keep ownership current

Review ownership as part of every reorganization, not afterwards. Stale ownership is worse than none. With no owner listed, people know to ask around. A wrong owner sends reviews and alerts to people who have no context, and they rubber-stamp or ignore them.

The CI step shown below enforces this in three checks:

  • It walks every source path and fails if any path matches no ownership rule.
  • It fails if any listed owner is not in the current team registry.
  • It compares the allowlist entry count against the base branch and fails if the count increased.

What does module ownership cost, when should you avoid it, and what are the alternatives?

The checks above keep the ownership map accurate. They don't make it free, so weigh the cost before rolling it out.

Illustrative estimate (assumed numbers, not a benchmark). Assume 150 PRs a week. 20% (30 PRs) need another team's approval, and each waits an extra 3 hours. Only a quarter of that wait blocks the author. Assume ownership prevents 8 misrouted PRs a week at 2 hours of rework each. It also routes 2 incidents a week 1 hour faster, with 3 responders on each.

Net hours/week = (avoided PRs × rework hours) + (incidents × hours saved × responders) − (gated PRs × added wait × blocking fraction) = (8 × 2) + (2 × 1 × 3) − (30 × 3 × 0.25) = 16 + 6 − 22.5 ≈ 0

That is roughly break-even. The blocking fraction drives the result, so measure it before you decide.

The other trade-offs:

  • A busy team gates everyone who touches its module.
  • Cross-cutting refactors need many approvals.
  • A platform-team bypass for mechanical changes is practical, but each bypass skips the owner's review.
  • Ownership that is too fine-grained creates review noise. Ownership that is too coarse recreates "no one owns it."
  • A shared database still couples modules.
  • A modular monolith still shares release cadence, build times and blast radius.

Skip module ownership for small single-team codebases and for code headed for deletion.

Approach Works when Main risk
Collective ownership One or two teams, high trust Nobody fixes unglamorous code
Layer-based (API/domain/data) Stable architecture, specialist teams Every feature crosses every team
Feature teams, no fixed ownership Broad codebase knowledge Design drift, unclear incident routing
Service extraction Independent scaling or deploys needed Network, data consistency, ops cost

Clear boundaries may show that extraction is unnecessary. If dependencies already flow one way through public interfaces, the remaining pain is often deploy coupling, which is cheaper to fix than adding a network boundary.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to monolith team ownership, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.