System Design Org Scale

Version Control for Large Projects

At ten engineers, Git is a tool. At a thousand, version control is an organizational architecture: vs , who must approve, how binaries are stored, and how releases are named for audit.

This note is the SD/org-scale angle—branching at scale, , LFS pain, review throughput, and tagging—not a beginner Git tutorial.

Scale journey

Atomic changes vs independent ship cadence.

Short branches; flags for incomplete work.

Route reviews; avoid orphan paths.

Tags map to digests and audits.

What actually happens

Version control answers three org questions: How do we change shared code safely? How do we keep clones and CI fast? How do we know exactly what ran in production last Tuesday?

A that worked for a startup (long feature branches, weekend merges) collapses when fifty teams touch the same platform. plus ownership automation is the usual industrial answer—not because Git Flow is “wrong,” but because integration delay becomes the dominant failure mode.

Binaries and ML weights break naïve assumptions: every clone pays for history. Policy for is part of VCS design.

Monorepo vs polyrepo

Diagram text: the exact Mermaid definition below preserves the nodes, labels, and connections. Enable JavaScript to view the rendered diagram.

Read the diagram definition

flowchart TB
    subgraph Mono["Monorepo"]
        M[One repo] --> T1[Service A]
        M --> T2[Service B]
        M --> L[Shared lib]
        C1[Atomic commit] --> T1
        C1 --> L
    end
    subgraph Poly["Polyrepo"]
        R1[Repo A] --> SA[Service A]
        R2[Repo B] --> SB[Service B]
        R3[Repo lib] --> Lib[Shared lib vN]
        SA -.->|depends on version| Lib
        SB -.->|depends on version| Lib
    end

Monorepo strengths

across callers
One toolchain and visibility into dependents
Easier large-scale API migrations in-tree
Shared CI templates and lint standards

Polyrepo strengths

Independent ship cadence per team
Smaller default clone and clearer ACL boundaries
Open-source style versioning of libraries
Less need for company-wide sparse-checkout tooling

Interview phrasing

Do not declare a religion. Say which failure mode you are optimizing against: and multi-repo migrations, or monorepo tooling and merge throughput—and name the mitigations you would fund.

Branching at org scale

Pattern	Works when…	Breaks when…
	Many teams, CD, strong tests	No flag discipline; flaky main
Short-lived PRs → main	Default for most SaaS	PRs grow to thousands of lines
Release branch per version	On-prem / mobile cut trains	Endless cherry-picks; stale trunk
Long feature branches	Tiny teams, rare deploys	Merge hell; hidden conflicts

Hotfix policy matters: fix on trunk first when possible, then cherry-pick to a release line. The opposite (fix only on release branch) guarantees the bug returns on the next cut.

From problem to mechanism

Problem. A platform team renames an internal auth header. Fifty services must update. In polyrepo, half ship this week; half next quarter. Outages appear as “random 401 storms.”

Naive system. Send Slack reminders and a wiki. Track a spreadsheet of versions. Hope.

Break it. A canary of the new auth service rejects old clients. There is no single commit that proves “all in-tree callers moved.”

Mechanism. Either (a) monorepo with targeted CI on affected packages, or (b) polyrepo with a dual-support window, versioned contracts, and a forced migration deadline with metrics. Ownership routes the review; release tags record who finished.

Correctness invariant for large VCS

Main (or each repo’s release line) has a defined “releasable” meaning; every production binary maps to a commit/tag; ownership is machine-readable; cross-cutting breaks are either atomic or explicitly dual-supported.

Code ownership and review bottlenecks

Diagram text: the exact Mermaid definition below preserves the nodes, labels, and connections. Enable JavaScript to view the rendered diagram.

Read the diagram definition

sequenceDiagram
    autonumber
    participant Eng as Engineer
    participant VCS as Version control
    participant CI as Targeted CI
    participant Own as CODEOWNERS
    participant Auto as Automerge policy

    Eng->>VCS: Small PR to owned path
    VCS->>CI: Affected targets only
    CI-->>VCS: Green
    VCS->>Own: Request required reviewers
    alt Owners responsive / automerge eligible
        Own-->>VCS: Approve
        Auto->>VCS: Merge to trunk
    else Owners saturated
        Note over Own,VCS: Queue grows; review bottleneck
        Eng->>Eng: Split PR / add secondary owners
    end

should match paging and domain expertise—not politics. Secondary owners and “readability” certifications (in Google-style orgs) spread load. Critical shared libraries need staffing proportional to consumer count.

A looks like: PRs idle for days, engineers batch huge diffs, quality drops, and people bypass review. Fix incentives (small PRs, SLA on reviews) and tooling (affected-target CI, suggested reviewers, automerge for generated code).

plaintext

Ownership anti-patterns
  - One person owns /common/** used by 200 services
  - CODEOWNERS requires 3 teams for a one-line typo
  - No owners → "LGTM from whoever is online"
  - Owners abroad with no follow-the-sun coverage

Mitigations
  - Split hot packages; add secondary owners
  - Automerge for low-risk paths (generated, format-only)
  - Review SLO: P50 < 4 working hours for small PRs
  - Design review before 2k-line migrations
  - Monorepo: path-based owners + sparse checkout for locals

Large binaries and LFS

Options: keep pointers in Git via ; store blobs in an artifact/object store and reference digests from code; or generate assets in CI from source. LFS helps but still needs quotas, auth, and selective fetch—otherwise every CI runner downloads the world.

Monorepos without amplify binary pain: a designer’s 2 GB video in /marketing slows every backend engineer’s clone.

Approach	When it fits	Watch for
Git LFS	Occasional media; modest size	Quota; CI full-fetch; lock files
Artifact registry + digest	Models, datasets, firmware	Provenance; access control
Generate in CI	Deterministic builds from source	Build time; toolchain drift
Commit raw blobs to Git	Almost never at scale	Clone explosion; rewrite history later

Worked example: monorepo CI targeting

plaintext

Change: //payments/fraud-rules/BUILD edited
Dependency graph (simplified):
  fraud-rules → checkout-api → edge-bff
  fraud-rules → batch-scorer

Targeted CI plan
  build + unit: fraud-rules, checkout-api, batch-scorer
  integration: checkout-api vs fraud-rules contract
  skip: unrelated maps/, ads/, ml-training/

Still always run
  repo-wide secret scan
  critical smoke: checkout happy path (cheap, high signal)

Failure mode if you skip graph analysis
  PR greens while checkout-api compile breaks
  → main red; org-wide merge freeze

Tooling implication
  Need a build system that understands targets (Bazel/Pants/etc.)
  or a disciplined package graph in the language ecosystem

Release tagging and audit

is how humans and machines agree on “what shipped.” Prefer immutable tags or release records that bind: service name → semver/calendar version → git SHA → artifact digest → config version.

Floating tags like prod that move silently defeat forensics. If you use them, treat them as pointers that must also log every move.

plaintext

Good release identity
  checkout-api@2026.10.10.14
    git:     abcdef123456
    image:   registry/checkout@sha256:9f3a…
    config:  config-set/checkout@7
    flags:   flag-snapshot/8821

Incident question you must answer in <5 minutes
  "Which commit and image digest are serving eu-west canary?"

Bad answers
  "Whatever was on main this morning"
  "The jar on disk named checkout-latest.jar"

Hybrid realities

Inner source monorepo + outer polyrepo

Core platform in one repo; satellite apps and mobile clients elsewhere. You still need versioned public APIs and compatibility windows for the outer ring.

Vendored third parties

Copying dependencies into the monorepo aids hermetic builds and audit; it increases tree size and update toil. Pin and automate upgrades.

Open-source mirrors

Public polyrepos for OSS; internal monorepo consumes pinned versions. Do not pretend public contribution workflows match internal trunk rules.

Acquisitions

New teams arrive with their own repos. Force-fitting a monorepo overnight fails; plan bridges: shared CI templates, contract tests, then gradual import.

Trade-offs

Choice	Gain	Cost
Monorepo	Atomic refactors; shared visibility	Tooling, sparse checkout, merge load
Polyrepo	Independent cadence; smaller clones	Version skew; multi-repo migrations
Trunk-based	Low integration risk; CD-friendly	Needs flags, fast CI, review capacity
Strict CODEOWNERS	Expert eyes; clear accountability	Review bottlenecks if understaffed
Git LFS	Keeps Git UX for some binaries	Ops, quotas; not ideal for huge models
Release branches	Stabilize trains / on-prem cuts	Cherry-pick debt; divergent lines

Choosing and explaining version control at org scale

A complete explanation connects the mechanism to a requirement. Describe what improves when you introduce it, which new failure cases become possible, and how you would know that the trade-off is worthwhile.

Explain the core idea

Repo topology is an architecture choice: monorepo for atomic consistency, polyrepo for independent ship—and hybrids are common.

Trunk-based development plus ownership automation keeps merge latency manageable; long feature branches do not scale.

Binaries, review capacity, and release identity (tag → digest) are first-class design concerns—not Git trivia.

When it belongs

Designing platform engineering for hundreds of services.

Explaining how a large refactor or API migration stays safe.

Discussing clone/CI cost, CODEOWNERS, or release auditability.

How it fails

Monorepo without targeted CI → eternal red main or hour-long PR loops.

Polyrepo without compatibility windows → version-skew outages.

Understaffed ownership of shared libraries → company-wide review queue.

Large binaries in plain Git → unusable clones and CI.

Trade-offs to weigh

Atomic change convenience versus tooling investment.

Independent repos versus migration coordination.

Strict owners versus throughput; automerge versus risk.

Common misunderstandings

Treating monorepo vs polyrepo as a morality debate instead of failure-mode design.

Confusing “we use Git” with having a scalable branching and ownership model.

Floating prod tags with no digest audit trail.

Wrap-up

Exercises

Pick a topology. 80 services, one shared auth library, mobile clients outside. Argue for monorepo, polyrepo, or hybrid—and list three tooling investments each choice forces.
Unstick reviews. A shared proto package has two owners and a 3-day P50 review time. Propose ownership, automerge, and PR-size rules that cut latency without abandoning expertise.
Binary policy. ML team wants to commit 8 GB weights. Design the storage and reference model so backend clones stay under 2 GB.

Topic-specific references

Why Google Stores Billions of Lines of Code in a Single Repository — classic monorepo rationale and tooling implications.
Trunk Based Development — branching patterns that scale with CD.
Git LFS — pointer model and operational caveats for large files.

Key takeaway

At scale, version control is how the organization coordinates change: choose repo topology for the migrations you fear most, keep trunk releasable, staff ownership, and make every production binary map to an immutable identity.