Monorepo vs Polyrepo: Which Should You Choose and Why?

# ─────────────────────────────────────────────
# 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('═══════════════════════════════════════');