Monorepo vs Polyrepo — How `affected` Prevents CI Meltdown

# ─────────────────────────────────────────────
# MONOREPO STRUCTURE — everything under one roof
# ─────────────────────────────────────────────
# acme-platform/                  <── single Git repository
#   apps/
#     customer-web/               <── React frontend
#     admin-dashboard/            <── Internal tools UI
#     mobile/                     <── React Native app
#   services/
#     auth-service/               <── Node.js authentication API
#     payments-service/           <── Python billing logic
#     notifications-service/      <── Go push notification worker
#   packages/
#     ui-components/              <── shared design system
#     validation-schemas/         <── shared Zod/Yup schemas
#     api-client/                 <── auto-generated API client
#   tools/
#     eslint-config/              <── shared lint rules
#     tsconfig/                   <── shared TypeScript configs
#   package.json                  <── workspace root
#   nx.json                       <── build orchestrator config

echo "One git clone. Everything available. One PR can touch frontend + backend + shared lib."
echo ""

# ─────────────────────────────────────────────
# POLYREPO STRUCTURE — each project its own repo
# ─────────────────────────────────────────────
# github.com/acme/customer-web         <── owns its own git history
# github.com/acme/admin-dashboard      <── independent release cycle
# github.com/acme/mobile               <── separate CI/CD pipeline
# github.com/acme/auth-service         <── team A owns this
# github.com/acme/payments-service     <── team B owns this
# github.com/acme/notifications-service
# github.com/acme/ui-components        <── published to npm as @acme/ui
# github.com/acme/validation-schemas   <── published to npm as @acme/validation
# github.com/acme/api-client           <── published to npm as @acme/api-client

echo "Nine separate clones. Shared code versioned via package manager (npm, pip, maven)."
echo "A change to ui-components requires: bump version → publish → update dependents → re-deploy."

# ─────────────────────────────────────────────────────────────
# GitHub Actions + Nx: Smart CI that only runs affected projects
# This is the tooling investment a healthy monorepo requires.
# Without this, every commit runs ALL tests — unusable at scale.
# ─────────────────────────────────────────────────────────────

name: Affected Projects CI

on:
  pull_request:
    branches: [main]

jobs:
  setup-affected:
    runs-on: ubuntu-latest
    outputs:
      # Nx computes which projects are affected by changed files
      affected-apps: ${{ steps.nx-affected.outputs.apps }}
      affected-libs: ${{ steps.nx-affected.outputs.libs }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # full history needed for Nx affected comparison

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Compute affected projects
        id: nx-affected
        run: |
          # Nx compares current branch to main and builds a dependency graph.
          # Only projects whose source files (or dependencies) changed are returned.
          AFFECTED_APPS=$(npx nx print-affected --type=app --select=projects --base=origin/main)
          AFFECTED_LIBS=$(npx nx print-affected --type=lib --select=projects --base=origin/main)
          echo "apps=$AFFECTED_APPS" >> $GITHUB_OUTPUT
          echo "libs=$AFFECTED_LIBS" >> $GITHUB_OUTPUT

  test-affected:
    needs: setup-affected
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Run tests only for affected projects
        run: |
          # If nothing is affected, this exits cleanly — no wasted CI minutes.
          # If payments-service changed, only payments-service and its dependents test.
          npx nx affected --target=test --base=origin/main --parallel=3

      - name: Run linting only for affected projects
        run: npx nx affected --target=lint --base=origin/main --parallel=3

      - name: Build affected projects (validates nothing is broken)
        run: npx nx affected --target=build --base=origin/main --parallel=3

// ─────────────────────────────────────────────────────────────
// packages/formatters/src/currency.ts
// This shared utility lives ONCE — used by web, mobile, and API
// ─────────────────────────────────────────────────────────────

export interface CurrencyFormatOptions {
  locale: string;       // e.g. 'en-US', 'de-DE', 'ja-JP'
  currency: string;     // ISO 4217 code e.g. 'USD', 'EUR', 'GBP'
  showSymbol?: boolean; // default true
}

/**
 * Formats a numeric amount as a locale-aware currency string.
 * Centralising this prevents subtle regional formatting bugs
 * (e.g. de-DE uses comma as decimal separator, not period).
 */
export function formatCurrency(
  amountInCents: number,
  options: CurrencyFormatOptions
): string {
  const { locale, currency, showSymbol = true } = options;

  // Convert cents to major currency unit — avoids floating point errors
  // from storing dollars/pounds directly (e.g. 0.1 + 0.2 !== 0.3 in JS)
  const amountInMajorUnit = amountInCents / 100;

  return new Intl.NumberFormat(locale, {
    style: showSymbol ? 'currency' : 'decimal',
    currency,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }).format(amountInMajorUnit);
}

// ─────────────────────────────────────────────────────────────
// MONOREPO USAGE — apps/customer-web/src/components/PriceTag.tsx
// Direct workspace import. No version pinning. Always current.
// ─────────────────────────────────────────────────────────────

// tsconfig paths or package.json workspaces maps this automatically:
import { formatCurrency } from '@acme/formatters'; // resolves to ../../packages/formatters/src

const priceTag = formatCurrency(4999, { locale: 'en-US', currency: 'USD' });
const germanPrice = formatCurrency(4999, { locale: 'de-DE', currency: 'EUR' });
const japanesePrice = formatCurrency(4999, { locale: 'ja-JP', currency: 'JPY', showSymbol: false });

console.log('US price:', priceTag);
console.log('German price:', germanPrice);
console.log('Japanese price (no symbol):', japanesePrice);

// ─────────────────────────────────────────────────────────────
// POLYREPO EQUIVALENT — requires these steps first:
// 1. cd acme-formatters-repo && npm version patch && npm publish
// 2. cd customer-web-repo && npm install @acme/formatters@1.0.1
// 3. Same steps in mobile-repo and invoicing-service-repo
// Each repo now potentially pinned to a different version.
// ─────────────────────────────────────────────────────────────

// import { formatCurrency } from '@acme/formatters'; // ^1.0.1 pinned in package.json

/**
 * A practical decision framework for monorepo vs polyrepo.
 * Answer each question honestly — the scores will tell a story.
 *
 * Run this with: node repo_strategy_decision_guide.js
 */

const teamProfile = {
  // How many engineers will work across multiple services regularly?
  crossFunctionalEngineers: 8,          // e.g. fullstack devs who touch frontend + backend

  // How many distinct deployable services exist (or are planned)?
  numberOfServices: 6,

  // Rough % of code that is shared across 2+ services
  sharedCodePercentage: 35,             // e.g. auth utils, design system, validation schemas

  // Do teams deploy together (coordinated) or independently?
  deploymentCoupling: 'coordinated',    // 'coordinated' | 'independent'

  // Is there a dedicated platform/DevOps team to maintain CI tooling?
  hasDedicatedPlatformTeam: false,

  // Approximate team size
  totalEngineers: 25,
};

function recommendRepoStrategy(profile) {
  let monorepoScore = 0;
  let polyrepoScore  = 0;
  const reasoning = [];

  // Cross-functional engineers benefit massively from monorepo atomic commits
  if (profile.crossFunctionalEngineers > 5) {
    monorepoScore += 3;
    reasoning.push('✓ High cross-functional headcount → monorepo atomic PRs save coordination time');
  } else {
    polyrepoScore += 2;
    reasoning.push('✓ Low cross-functional work → polyrepo team boundaries are clean and respected');
  }

  // High shared code % makes polyrepo painful (version fragmentation)
  if (profile.sharedCodePercentage > 25) {
    monorepoScore += 3;
    reasoning.push('✓ High shared code (>25%) → polyrepo means constant version bumping and fragmentation risk');
  } else {
    polyrepoScore += 2;
    reasoning.push('✓ Low shared code → polyrepo versioning overhead is manageable');
  }

  // Coordinated deployments align naturally with monorepo PRs
  if (profile.deploymentCoupling === 'coordinated') {
    monorepoScore += 2;
    reasoning.push('✓ Coordinated deployments → monorepo keeps services in sync naturally');
  } else {
    polyrepoScore += 3;
    reasoning.push('✓ Independent deployments → polyrepo respects service autonomy and release cadence');
  }

  // Monorepo tooling investment needs someone to own it
  if (!profile.hasDedicatedPlatformTeam && profile.numberOfServices > 8) {
    polyrepoScore += 2;
    reasoning.push('⚠ No platform team + many services → monorepo CI tooling becomes a maintenance burden');
  } else if (profile.hasDedicatedPlatformTeam) {
    monorepoScore += 2;
    reasoning.push('✓ Platform team present → monorepo tooling (Nx/Turborepo) will be properly maintained');
  }

  // Small teams (<15 engineers) often find polyrepo overhead manageable
  if (profile.totalEngineers < 15) {
    polyrepoScore += 1;
    reasoning.push('✓ Small team → polyrepo simplicity outweighs monorepo tooling setup cost');
  } else if (profile.totalEngineers > 50) {
    monorepoScore += 2;
    reasoning.push('✓ Large team → monorepo discoverability and shared standards become critical at scale');
  }

  const recommendation = monorepoScore > polyrepoScore
    ? 'MONOREPO'
    : monorepoScore === polyrepoScore
      ? 'HYBRID (start polyrepo, merge into monorepo when shared code pain hits)'
      : 'POLYREPO';

  return { recommendation, monorepoScore, polyrepoScore, reasoning };
}

const result = recommendRepoStrategy(teamProfile);

console.log('═══════════════════════════════════════');
console.log('  REPO STRATEGY DECISION FRAMEWORK');
console.log('═══════════════════════════════════════');
console.log(`  Monorepo Score : ${result.monorepoScore}`);
console.log(`  Polyrepo Score : ${result.polyrepoScore}`);
console.log(`  Recommendation : ${result.recommendation}`);
console.log('───────────────────────────────────────');
console.log('  Reasoning:');
result.reasoning.forEach(reason => console.log(`  ${reason}`));
console.log('═══════════════════════════════════════');

# ─────────────────────────────────────────────────────────────
# Migrate one polyrepo into a monorepo component
# Uses git-filter-repo to preserve full history
# ─────────────────────────────────────────────────────────────

# Step 1: In a temporary directory, clone the repo you want to move
cd /tmp
gh repo clone acme/auth-service
cd auth-service

# Step 2: Strip all tags (they won't be meaningful in the monorepo)
git tag -l | xargs git tag -d 2>/dev/null

# Step 3: Rewrite history to pretend all files lived under services/auth-service/
git filter-repo --to-subdirectory-filter services/auth-service --force

# Step 4: Move the rewritten repo into the monorepo clone
cd /path/to/monorepo
# Add the auth-service remote and merge
# Ensure the monorepo is clean

git remote add auth-service /tmp/auth-service
git fetch auth-service --no-tags

# Step 5: Merge all history into main branch
git merge auth-service/main --allow-unrelated-histories --no-edit

# Step 6: Clean up
git remote remove auth-service
rm -rf /tmp/auth-service

echo "Migration complete. Verify with: git log --oneline -- graph services/auth-service/"

// io.thecodeforge — cs-fundamentals tutorial

import json

# Simulating a monorepo build decision
changed_dirs = ["services/payment", "libs/common"]
affected_projects = []

for dir in changed_dirs:
    if "libs/" in dir:
        # Shared lib changed — rebuild all dependents
        affected_projects.append("*")
    else:
        affected_projects.append(dir)

if "*" in affected_projects:
    print("Full rebuild triggered — estimated time: 32m 14s")
else:
    print(f"Partial rebuild: {affected_projects} — estimated: 4m 12s")

# Polyrepo check
if len(set(changed_dirs)) > 5:
    print("Warning: cross-repo dependencies detected. Sync release tags.")

// io.thecodeforge — cs-fundamentals tutorial

# Simulating a CODEOWNERS check for a monorepo
import os

team_map = {
    "services/payment": "@team-payment",
    "services/shipping": "@team-shipping",
    "libs/common": "@team-platform",
}

changed_file = "services/payment/src/handler.py"
owners = None
for path, team in team_map.items():
    if changed_file.startswith(path):
        owners = team
        break

if owners:
    print(f"Requiring approval from {owners}")
else:
    print("No ownership defined. Anyone can break this.")
    print("Production Incident: 85% chance of unapproved change.")

// io.thecodeforge — cs-fundamentals tutorial

import json

def find_dependency_conflicts(repos):
    """Detect version conflicts across polyrepo packages."""
    versions = {}
    for repo, deps in repos.items():
        for pkg, ver in deps.items():
            if pkg in versions and versions[pkg] != ver:
                print(f"CONFLICT: {pkg} wants {ver} in {repo}, but {versions[pkg]} elsewhere")
            versions[pkg] = ver
    return versions

repos = {
    "service-a": {"auth-lib": "1.2.0", "http-client": "3.0.1"},
    "service-b": {"auth-lib": "1.3.0", "http-client": "2.9.8"},
}
find_dependency_conflicts(repos)

// io.thecodeforge — cs-fundamentals tutorial

def update_auth_flow(schema, backend, frontend):
    """Simulate an atomic cross-service change in a monorepo."""
    changes = [
        ("database/schema.sql", schema),
        ("auth-service/main.py", backend),
        ("web-client/auth.js", frontend),
    ]
    for path, content in changes:
        print(f"WRITE: {path}")
        print(f"CHANGE: {content[:40]}...")
    print("\nCOMMIT: 1 change, 1 CI run, 1 deploy")

update_auth_flow(
    "ALTER TABLE users ADD role VARCHAR(50)",
    "def get_user_role(user_id): ...",
    "if user.role === 'admin': show_panel()"
)

// io.thecodeforge — cs-fundamentals tutorial

def monorepo_health_check(team_size, lines_of_code, ci_minutes):
    """Quick threshold check for monorepo scaling issues."""
    if team_size > 500 and lines_of_code > 5_000_000:
        print("WARNING: You need Bazel or similar build system.")
    if ci_minutes > 15:
        print(f"CI takes {ci_minutes} min — slowdown imminent.")
        print("ACTION: Add path filters or split into smaller monorepos.")
    if team_size < 50:
        print("Monorepo is fine. Stop overthinking.")

monorepo_health_check(team_size=1200, lines_of_code=12_000_000, ci_minutes=22)

// io.thecodeforge — cs-fundamentals tutorial
import os

REPO_TYPE = os.getenv('REPO_STRATEGY', 'unknown')
TEAM_SIZE = int(os.getenv('TEAM_SIZE', 5))

if REPO_TYPE == 'monorepo' and TEAM_SIZE < 15:
    print('Warning: Monorepo overhead may slow small teams.')
elif REPO_TYPE == 'polyrepo' and TEAM_SIZE > 50:
    print('Warning: Polyrepo coordination cost grows fast.')
else:
    print('Strategy fits team size. Proceed.')

// io.thecodeforge — cs-fundamentals tutorial
import time

def measure_flexibility(repo_count, change_depth):
    start = time.time()
    # Simulate cross-repo coordination
    time.sleep(repo_count * 0.5 * change_depth)
    elapsed = time.time() - start
    return elapsed

# Two scenarios
flex_time = measure_flexibility(5, 1)  # 5 repos, shallow change
agile_time = measure_flexibility(1, 5)  # 1 repo, deep change

print(f'Flexibility cost: {flex_time:.2f}s')
print(f'Agility cost: {agile_time:.2f}s')