Frontend Scalability & Team Architecture

src/
  features/
    catalog/               # product discovery domain
      components/
        ProductCard.tsx
        ProductGrid.tsx
        ProductFilters.tsx
      hooks/
        useProducts.ts
        useProductSearch.ts
        useProductFilters.ts
      types/
        product.ts
      schemas/
        product.ts
      __tests__/
        useProducts.test.ts
        ProductCard.test.tsx
      index.ts             # public API — only what other features may use

    cart/                  # purchase intent domain
      components/
        CartDrawer.tsx
        CartItem.tsx
        CartSummary.tsx
      hooks/
        useCart.ts
        useCartSync.ts
      types/
        cart.ts
      index.ts

    checkout/              # transaction domain
      components/
      hooks/
      types/
      index.ts

  shared/                  # cross-feature primitives (not business logic)
    components/
      Button.tsx
      Modal.tsx
      Spinner.tsx
    hooks/
      useDebounce.ts
      useLocalStorage.ts
    lib/
      api-client.ts
      query-client.ts
    types/
      common.ts

  app/                     # routing and page composition only
    (shop)/
      page.tsx
      layout.tsx
    cart/
      page.tsx

// Public API for the catalog feature.
// Other features and pages import from here, never from internal paths.

// Components available for composition in pages
export { ProductCard } from "./components/ProductCard";
export { ProductGrid } from "./components/ProductGrid";

// Hooks available for use in page-level orchestration
export { useProducts } from "./hooks/useProducts";
export { useProductSearch } from "./hooks/useProductSearch";

// Types needed by consumers
export type { Product, ProductFilters, ProductSortOrder } from "./types/product";

// NOT exported: internal hooks, sub-components, implementation details
// ProductFilters component is internal — only ProductGrid uses it
// useProductFilters hook is internal to useProductSearch

module.exports = {
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            // Forbid importing from another feature's internals
            // Only imports from a feature's index.ts are allowed
            group: ["@/features/*/components/*", "@/features/*/hooks/*", "@/features/*/types/*"],
            message:
              "Import from a feature's public API (index.ts) only. " +
              "Direct internal imports create hidden coupling.",
          },
        ],
      },
    ],
  },
};

// Catalog context: cares about display and discovery
// features/catalog/types/product.ts
export interface CatalogProduct {
  id: string;
  name: string;
  slug: string;
  price: number;
  thumbnailUrl: string;
  rating: number;
  inStock: boolean;
  category: string;
}

// Cart context: cares about purchase intent and quantities
// features/cart/types/cart-item.ts
export interface CartItem {
  productId: string;
  productName: string;     // denormalised for display without catalog lookup
  unitPrice: number;
  quantity: number;
  variantId?: string;
}

// Order context: cares about fulfilment and history
// features/orders/types/order.ts
export interface OrderLineItem {
  sku: string;
  description: string;
  quantity: number;
  unitPricePaid: number;  // historical — may differ from current price
  discount: number;
}

// Each context owns its model. Duplication of fields is deliberate —
// coupling contexts through a shared Product type creates the wrong dependency.

// External API uses snake_case and different field names.
// The ACL translates once at the boundary — domain code never sees the external shape.

import type { ExternalProductDTO } from "@/shared/lib/api-client";
import type { CatalogProduct } from "../types/product";

export function adaptProduct(dto: ExternalProductDTO): CatalogProduct {
  return {
    id: dto.product_id,
    name: dto.product_name,
    slug: dto.url_slug,
    price: dto.price_cents / 100,
    thumbnailUrl: dto.images?.[0]?.url ?? "/placeholder.png",
    rating: dto.average_rating ?? 0,
    inStock: dto.inventory_status === "IN_STOCK",
    category: dto.category_code.toLowerCase().replace(/_/g, "-"),
  };
}

export function adaptProductList(dtos: ExternalProductDTO[]): CatalogProduct[] {
  return dtos.map(adaptProduct);
}

// Usage in the data-fetching layer — the rest of the feature uses CatalogProduct
async function fetchProducts(filters: ProductFilters): Promise<CatalogProduct[]> {
  const response = await apiClient.get<ExternalProductDTO[]>("/v2/products", filters);
  return adaptProductList(response.data);
}

// Lightweight domain event bus — no external library needed at this scale.

type Handler<T> = (payload: T) => void;

class DomainEventBus {
  private handlers = new Map<string, Handler<unknown>[]>();

  emit<T>(event: string, payload: T): void {
    (this.handlers.get(event) ?? []).forEach((h) => h(payload as unknown));
  }

  on<T>(event: string, handler: Handler<T>): () => void {
    const existing = this.handlers.get(event) ?? [];
    this.handlers.set(event, [...existing, handler as Handler<unknown>]);
    return () => {
      const updated = (this.handlers.get(event) ?? []).filter((h) => h !== handler);
      this.handlers.set(event, updated);
    };
  }
}

export const domainEvents = new DomainEventBus();

// Domain event type registry — keeps events typed end-to-end
export interface DomainEventMap {
  "cart:item-added": { productId: string; quantity: number };
  "cart:item-removed": { productId: string };
  "cart:cleared": Record<string, never>;
  "checkout:completed": { orderId: string; total: number };
  "user:signed-in": { userId: string; role: string };
  "user:signed-out": Record<string, never>;
}

// Typed emit and on helpers
export function emit<K extends keyof DomainEventMap>(
  event: K,
  payload: DomainEventMap[K]
): void {
  domainEvents.emit(event, payload);
}

export function on<K extends keyof DomainEventMap>(
  event: K,
  handler: Handler<DomainEventMap[K]>
): () => void {
  return domainEvents.on(event, handler);
}

my-org/
  apps/
    web/                   # main customer-facing Next.js app
    admin/                 # internal admin dashboard
    marketing/             # marketing/landing pages (separate deployment)
    docs/                  # internal documentation site

  packages/
    ui/                    # shared component library
      src/
        components/
        tokens/
      package.json         # @my-org/ui
    api-client/            # typed API client shared across apps
      src/
      package.json         # @my-org/api-client
    config/                # shared tooling configs
      eslint/
      tsconfig/
      vitest/
      package.json         # @my-org/config
    types/                 # shared TypeScript types (API contracts, etc.)
      package.json         # @my-org/types
    utils/                 # shared pure utilities (formatting, validation helpers)
      package.json         # @my-org/utils

  turbo.json
  package.json             # root workspace
  pnpm-workspace.yaml      # or npm/yarn workspaces

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "__tests__/**", "vitest.config.ts"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc.js"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

{
  "name": "@my-org/ui",
  "version": "1.4.2",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./tokens": {
      "import": "./dist/tokens/index.js",
      "types": "./dist/tokens/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm --dts",
    "dev": "tsup src/index.ts --format esm --dts --watch",
    "test": "vitest run",
    "lint": "eslint src",
    "typecheck": "tsc --noEmit"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@my-org/config": "workspace:*",
    "tsup": "^8.0.0"
  }
}

name: CI

on: [push, pull_request]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # required for Turborepo to detect affected packages

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci
        # or: yarn install --frozen-lockfile
        # or: pnpm install --frozen-lockfile

      - name: Build, lint, typecheck, and test (affected only)
        run: npx turbo run build lint typecheck test --filter=...[origin/main]
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import federation from "@originjs/vite-plugin-federation";

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: "host",
      remotes: {
        // Each remote is a separately deployed app
        catalog: "http://localhost:3001/assets/remoteEntry.js",
        checkout: "http://localhost:3002/assets/remoteEntry.js",
      },
      shared: {
        react: { singleton: true, requiredVersion: "^19.0.0" },
        "react-dom": { singleton: true, requiredVersion: "^19.0.0" },
        "@tanstack/react-query": { singleton: true },
      },
    }),
  ],
  build: {
    target: "esnext",
    minify: false,
    cssCodeSplit: false,
  },
});

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import federation from "@originjs/vite-plugin-federation";

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: "catalog",
      filename: "remoteEntry.js",
      exposes: {
        // Only expose stable, well-tested surfaces
        "./ProductCatalog": "./src/components/ProductCatalog",
        "./ProductSearch": "./src/components/ProductSearch",
      },
      shared: {
        react: { singleton: true },
        "react-dom": { singleton: true },
        "@tanstack/react-query": { singleton: true },
      },
    }),
  ],
  build: {
    target: "esnext",
    minify: false,
    cssCodeSplit: false,
  },
});

import React, { Suspense, lazy } from "react";

// Lazy-loaded remote component — type the import explicitly
const ProductCatalog = lazy(
  () => import("catalog/ProductCatalog") as Promise<{ default: React.ComponentType<CatalogProps> }>
);

interface CatalogProps {
  category?: string;
  onProductSelect: (productId: string) => void;
}

export function ShopPage() {
  const handleProductSelect = (productId: string) => {
    // Cross-MFE navigation via shared router or custom event
    window.dispatchEvent(new CustomEvent("navigate", { detail: { path: `/product/${productId}` } }));
  };

  return (
    <Suspense fallback={<CatalogSkeleton />}>
      <ProductCatalog onProductSelect={handleProductSelect} />
    </Suspense>
  );
}

// Design tokens: the semantic layer — not raw values, but meanings.
// Tools like Style Dictionary or Token Transformer generate these from
// a Figma-exported token JSON. The structure here is consumed directly.

export const tokens = {
  color: {
    // Semantic aliases — components use these, not raw values
    background: {
      primary: "var(--color-bg-primary)",
      secondary: "var(--color-bg-secondary)",
      elevated: "var(--color-bg-elevated)",
      inverse: "var(--color-bg-inverse)",
    },
    text: {
      primary: "var(--color-text-primary)",
      secondary: "var(--color-text-secondary)",
      disabled: "var(--color-text-disabled)",
      inverse: "var(--color-text-inverse)",
    },
    brand: {
      primary: "var(--color-brand-primary)",
      primaryHover: "var(--color-brand-primary-hover)",
      secondary: "var(--color-brand-secondary)",
    },
    feedback: {
      error: "var(--color-error)",
      warning: "var(--color-warning)",
      success: "var(--color-success)",
      info: "var(--color-info)",
    },
  },
  spacing: {
    0: "0",
    1: "0.25rem",
    2: "0.5rem",
    3: "0.75rem",
    4: "1rem",
    6: "1.5rem",
    8: "2rem",
    12: "3rem",
    16: "4rem",
  },
  radius: {
    sm: "4px",
    md: "8px",
    lg: "12px",
    xl: "16px",
    full: "9999px",
  },
  shadow: {
    sm: "0 1px 2px rgba(0,0,0,0.05)",
    md: "0 4px 6px rgba(0,0,0,0.07)",
    lg: "0 10px 15px rgba(0,0,0,0.1)",
  },
} as const;

export type DesignTokens = typeof tokens;

import React from "react";
import styles from "./Button.module.css";

export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /** Visual hierarchy. 'primary' for main CTA, 'secondary' for alternatives, 'ghost' for low emphasis. */
  variant?: "primary" | "secondary" | "ghost" | "danger";
  /** Size affects padding and font size. Default is 'md'. */
  size?: "sm" | "md" | "lg";
  /** Renders a loading spinner and disables interaction. */
  loading?: boolean;
  /** Renders icon on the left of the label. */
  leadingIcon?: React.ReactNode;
  /** Renders icon on the right of the label. */
  trailingIcon?: React.ReactNode;
  /** Use 'full' to stretch to container width. */
  width?: "auto" | "full";
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      variant = "primary",
      size = "md",
      loading = false,
      leadingIcon,
      trailingIcon,
      width = "auto",
      children,
      disabled,
      className,
      ...rest
    },
    ref
  ) => {
    return (
      <button
        ref={ref}
        disabled={disabled || loading}
        aria-busy={loading || undefined}
        data-variant={variant}
        data-size={size}
        data-width={width}
        className={[styles.button, className].filter(Boolean).join(" ")}
        {...rest}
      >
        {loading ? (
          <span className={styles.spinner} aria-hidden="true" />
        ) : leadingIcon ? (
          <span className={styles.icon} aria-hidden="true">{leadingIcon}</span>
        ) : null}
        <span className={styles.label}>{children}</span>
        {!loading && trailingIcon && (
          <span className={styles.icon} aria-hidden="true">{trailingIcon}</span>
        )}
      </button>
    );
  }
);

Button.displayName = "Button";

# RFC 0023: Adopt Zod as the Standard Validation Library

## Status
Accepted — 2026-03-14

## Author
Mahsa Mohajer (@mahsamohajer)

## Summary
Adopt Zod as the single standard for runtime validation across all applications
in the monorepo. Replace the current mix of yup, custom validators, and unvalidated
API responses.

## Problem
Currently we have three different validation libraries in use (yup in checkout,
joi in admin, hand-rolled validators in web). This creates inconsistent error
message formats, duplicated schema logic for the same domain types, and a
maintenance burden when shared types change.

## Proposal
1. Add @my-org/schemas package to the monorepo with shared Zod schemas for all
   API contracts.
2. Deprecate yup and joi in consuming apps. Provide migration guides.
3. Enforce: all API boundary validation must use Zod schemas from @my-org/schemas
   or app-local schemas. No other validation libraries in new code.

## Alternatives Considered
- Valibot: smaller bundle, similar API. Rejected: smaller ecosystem, less TypeScript
  integration maturity at time of decision.
- Type assertions only: rejected, defeats the purpose of runtime validation.

## Migration Plan
Phase 1 (April): Create @my-org/schemas. All new code uses Zod.
Phase 2 (Q3): Migrate existing validation in checkout and admin.
Phase 3 (Q4): Remove yup and joi from the dependency graph.

## Decision Record
Accepted with the condition that a Zod-to-yup migration guide is published
before Phase 2 begins.

// Track tech debt as typed, queryable records rather than TODO comments.
// Run a script to extract and report on outstanding debt by owner and severity.

export const techDebtRegistry = [
  {
    id: "TD-001",
    title: "Migrate checkout form to Zod validation",
    severity: "high" as const,
    owner: "checkout-team",
    effort: "medium" as const,
    addedDate: "2026-01-15",
    context:
      "Currently uses yup schemas. Will be blocked from the next major design system update " +
      "until migrated. Part of RFC-0023 migration plan.",
    linkedRfc: "RFC-0023",
  },
  {
    id: "TD-002",
    title: "Remove direct react-query imports in feature components",
    severity: "medium" as const,
    owner: "catalog-team",
    effort: "low" as const,
    addedDate: "2026-02-20",
    context:
      "About 12 components import useQuery directly. They should use the domain hooks " +
      "which provide the correct cache key structure. Creates inconsistent caching behaviour.",
    linkedRfc: null,
  },
] satisfies TechDebtItem[];

interface TechDebtItem {
  id: string;
  title: string;
  severity: "critical" | "high" | "medium" | "low";
  owner: string;
  effort: "high" | "medium" | "low";
  addedDate: string;
  context: string;
  linkedRfc: string | null;
}

# CODEOWNERS — required reviewer assignments for pull requests.
# Format: path pattern [space] @team-or-username

# Monorepo shared packages: platform team owns
/packages/ui/           @my-org/platform-team
/packages/api-client/   @my-org/platform-team
/packages/config/       @my-org/platform-team

# Application features: stream-aligned team ownership
/apps/web/src/features/catalog/     @my-org/catalog-team
/apps/web/src/features/cart/        @my-org/cart-team
/apps/web/src/features/checkout/    @my-org/checkout-team
/apps/web/src/features/account/     @my-org/account-team

# Shared app infrastructure: all changes require platform review
/apps/web/src/shared/               @my-org/platform-team
/apps/web/middleware.ts             @my-org/platform-team
/apps/web/app/layout.tsx            @my-org/platform-team @my-org/frontend-leads

# CI/CD: devex team owns
/.github/                           @my-org/devex-team
/turbo.json                         @my-org/devex-team

# Architecture docs and RFCs: frontend leads review
/docs/rfcs/                         @my-org/frontend-leads
/docs/decisions/                    @my-org/frontend-leads

# Contributing to @my-org/ui

## Who can contribute
All engineers at my-org can contribute. The platform team owns and reviews all changes.

## For bug fixes
1. Open an issue with reproduction steps.
2. Assign to yourself or ask the platform team to assign it.
3. Open a PR. All CI checks must pass. One platform team approval required.

## For new components
1. Raise a proposal in #design-system-proposals Slack channel first.
2. Get sign-off from a designer and the platform team lead.
3. Open an RFC if the component requires new design tokens or API patterns.
4. Implement with Storybook stories and at least 80% test coverage.
5. Two approvals required (one platform team, one from another stream team).

## For breaking changes
1. Open an RFC. ARB review required.
2. Run a codemod for automated migration where possible.
3. Deprecation period of one minor version before breaking change lands.
4. Update all apps in the monorepo as part of the same PR.

## SLA
Platform team reviews within 2 business days. Escalate in #platform-team if blocked.

# Week One: Frontend Engineering Onboarding

## Day 1: Environment and orientation
- [ ] Dev environment setup (follow docs/setup.md)
- [ ] First PR: add name to ENGINEERS.md
- [ ] Walk through the monorepo structure with your team lead
- [ ] Read the three most recent merged RFCs

## Day 2-3: Domain deep-dive
- [ ] Read the architecture overview for your assigned feature domain
- [ ] Pair with a teammate on an in-flight bug fix
- [ ] Review five recent merged PRs in your domain
- [ ] Shadow a production deployment

## Day 4-5: First contribution
- [ ] Pick a "good first issue" from your team's backlog
- [ ] Implement, test, and get the PR reviewed
- [ ] Attend team standup and retrospective

## End of week 1 goals
- Can run the full test suite and make a change that passes CI
- Understands the feature boundary model and where your team's code lives
- Has shipped at least one small change to production

## Resources
- Architecture overview: docs/architecture/README.md
- Coding standards: docs/standards/frontend.md
- Team RFCs: docs/rfcs/
- Your buddy: [assigned at start of week]

// Identify files with only one contributor — knowledge silos.
// Run as a health check on PRs or periodically in CI.
import { execSync } from "child_process";

interface FileSilo {
  path: string;
  contributor: string;
  lastModified: string;
}

function findKnowledgeSilos(directory = "src", threshold = 1): FileSilo[] {
  const files = execSync(`git ls-files ${directory}`)
    .toString()
    .split("\n")
    .filter(Boolean);

  const silos: FileSilo[] = [];

  for (const file of files) {
    const contributors = execSync(`git log --format="%ae" -- "${file}"`)
      .toString()
      .split("\n")
      .filter(Boolean);

    const unique = new Set(contributors);

    if (unique.size <= threshold) {
      const lastModified = execSync(`git log -1 --format="%as" -- "${file}"`)
        .toString()
        .trim();

      silos.push({
        path: file,
        contributor: [...unique][0],
        lastModified,
      });
    }
  }

  return silos;
}

// Typed feature flag system — works with any provider (LaunchDarkly, Unleash,
// custom SSE endpoint, or static config for simpler setups).

export type FeatureFlags = {
  "new-checkout-flow": boolean;
  "ai-search-suggestions": boolean;
  "product-reviews-v2": boolean;
  "cart-persistence": boolean;
};

type FlagName = keyof FeatureFlags;

// Flag client interface — injectable for testing
export interface FlagClient {
  isEnabled<K extends FlagName>(flag: K, context?: FlagContext): boolean;
}

interface FlagContext {
  userId?: string;
  orgId?: string;
  email?: string;
}

// React hook for consuming flags
export function useFlag<K extends FlagName>(flag: K): boolean {
  const client = useFlagClient(); // from FlagProvider context
  const { userId } = useSession();
  return client.isEnabled(flag, { userId });
}

// Provider pattern — wraps the actual flag client (LaunchDarkly, Unleash, etc.)
export function FlagProvider({
  client,
  children,
}: {
  client: FlagClient;
  children: React.ReactNode;
}) {
  return (
    <FlagContext.Provider value={client}>
      {children}
    </FlagContext.Provider>
  );
}

// Usage in components — flag name is typed, refactor-safe
function CheckoutButton() {
  const useNewFlow = useFlag("new-checkout-flow");

  return useNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
}

// Progressive rollout: route a percentage of traffic to a new experience.
// Works with feature flags that support user-segment targeting.

interface RolloutConfig {
  flag: string;
  percentage: number;    // 0-100
  sticky: boolean;       // same user always gets same variant
}

// Middleware-level rollout (Next.js)
export function getExperimentVariant(
  userId: string,
  rollout: RolloutConfig
): "control" | "treatment" {
  if (!rollout.sticky) {
    return Math.random() * 100 < rollout.percentage ? "treatment" : "control";
  }

  // Sticky assignment: hash userId + flag name for consistent bucketing
  const hash = simpleHash(userId + rollout.flag);
  const bucket = hash % 100;
  return bucket < rollout.percentage ? "treatment" : "control";
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = (hash << 5) - hash + str.charCodeAt(i);
    hash |= 0;
  }
  return Math.abs(hash);
}

# Frontend Architecture Overview

## System context
The frontend is a Next.js 16 monorepo application serving consumer and admin
experiences. It communicates with a microservices backend via REST APIs and a
GraphQL federation gateway. Real-time features use Server-Sent Events.

## Container view
- apps/web: Main consumer-facing application (Next.js 16, App Router)
- apps/admin: Internal admin dashboard (Next.js 16)
- packages/ui: Shared component library (@my-org/ui, tsup-built)
- packages/api-client: Typed API client (@my-org/api-client, auto-generated from OpenAPI)

## Feature domains (component view)
- catalog: Product discovery, search, filtering (catalog-team)
- cart: Purchase intent, cart management (cart-team)
- checkout: Transaction flow, payment, confirmation (checkout-team)
- account: User profile, order history, preferences (account-team)

## Key decisions
- ADR-012: Feature-based directory structure (see docs/decisions/012-feature-structure.md)
- ADR-019: TanStack Query for server state (see docs/decisions/019-server-state.md)
- ADR-023: Zod for runtime validation (see docs/rfcs/0023-adopt-zod-validation.md)
- ADR-031: Trunk-based development with feature flags (see docs/decisions/031-tbd.md)

## Data flow
User request -> Next.js middleware (auth, feature flags)
  -> App Router layout (global providers, session)
  -> Feature page (domain-specific data fetching via TanStack Query)
  -> API client (@my-org/api-client) -> Backend services

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    optimizePackageImports: [
      "@my-org/ui",
      "date-fns",
      "recharts",
      "lucide-react",
    ],
  },
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.optimization.splitChunks = {
        chunks: "all",
        cacheGroups: {
          // Separate vendor chunk per feature domain — teams own their bundle cost
          catalogVendors: {
            name: "vendors-catalog",
            test: /[\/]features[\/]catalog[\/]/,
            priority: 30,
          },
          checkoutVendors: {
            name: "vendors-checkout",
            test: /[\/]features[\/]checkout[\/]/,
            priority: 30,
          },
          // Shared component library in its own chunk
          ui: {
            name: "ui-library",
            test: /[\/]node_modules[\/]@my-org[\/]ui[\/]/,
            priority: 40,
          },
          // Framework chunk: rarely changes, high cache hit rate
          framework: {
            name: "framework",
            test: /[\/]node_modules[\/](react|react-dom|next)[\/]/,
            priority: 50,
          },
        },
      };
    }
    return config;
  },
};

export default nextConfig;

// Fail CI if any bundle chunk exceeds its budget.
// Run after next build to check .next/analyze/ output.

interface BundleBudget {
  name: string;
  maxKB: number;
  critical: boolean;
}

const budgets: BundleBudget[] = [
  { name: "framework", maxKB: 120, critical: true },
  { name: "ui-library", maxKB: 80, critical: true },
  { name: "vendors-catalog", maxKB: 60, critical: false },
  { name: "vendors-checkout", maxKB: 100, critical: true }, // payment libs allowed more
  { name: "main", maxKB: 200, critical: true },
];

// Parse the .next/build-manifest.json and check each chunk size.
// Exit 1 (fail CI) if any critical budget is exceeded.
// Warn (but pass) for non-critical overages.

# Check the bundle cost of a dependency before adding it
npx bundlephobia recharts
# or: yarn dlx bundlephobia recharts

# Audit all dependencies for size and treeshakeability
npx bundlephobia --all package.json

# Analyse the current Next.js bundle composition
ANALYZE=true npm run build
# or: ANALYZE=true yarn build
# Opens @next/bundle-analyzer in the browser

name: Sharded Tests

on: [push, pull_request]

jobs:
  vitest-sharded:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
        # or: yarn install --frozen-lockfile

      - name: Run tests (shard ${{ matrix.shard }} of 4)
        run: npx vitest run --reporter=junit --outputFile=results/shard-${{ matrix.shard }}.xml --shard=${{ matrix.shard }}/4

  playwright-sharded:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci && npx playwright install --with-deps
        # or: yarn install --frozen-lockfile && npx playwright install --with-deps

      - name: Run E2E (shard ${{ matrix.shard }} of 3)
        run: npx playwright test --shard=${{ matrix.shard }}/3

// Contract test: assert that the API client's expected shape matches
// the actual backend response. Catches API drift early without full E2E.
// Run in CI against a staging environment or a recorded interaction.

import { describe, it, expect } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { createApiClient } from "@my-org/api-client";
import { catalogProductSchema } from "@my-org/types/schemas";

const server = setupServer(
  http.get("https://api.example.com/v1/products", () =>
    HttpResponse.json({
      data: [
        {
          product_id: "prod_001",
          product_name: "Test Widget",
          price_cents: 2999,
          inventory_status: "IN_STOCK",
          url_slug: "test-widget",
          category_code: "ELECTRONICS",
          images: [{ url: "https://cdn.example.com/widget.jpg" }],
          average_rating: 4.2,
        },
      ],
      total: 1,
    })
  )
);

beforeAll(() => server.listen());
afterAll(() => server.close());

describe("products API contract", () => {
  it("response matches the expected schema", async () => {
    const client = createApiClient({ baseUrl: "https://api.example.com" });
    const products = await client.catalog.listProducts({});

    expect(products.length).toBeGreaterThan(0);

    for (const product of products) {
      // Zod parse — throws if the shape diverges from the contract
      const result = catalogProductSchema.safeParse(product);
      expect(result.success).toBe(true);
    }
  });
});

// ANTI-PATTERN
// One Zustand store holds state for every feature.
// As the codebase grows, every team edits the same file.
// State shape changes break other teams. No clear ownership.
const useStore = create<{
  user: User | null;
  cart: CartItem[];
  products: Product[];
  checkoutStep: number;
  adminFilters: AdminFilters;
  // ... 40 more fields from 8 different teams
}>((set) => ({ /* ... */ }));

// CORRECT: Feature-scoped stores with domain events for cross-feature updates
// features/cart/stores/cartStore.ts
export const useCartStore = create<CartState>((set) => ({
  items: [],
  addItem: (item) => set((s) => ({ items: [...s.items, item] })),
  clearCart: () => set({ items: [] }),
}));

// Cross-feature communication via domain events, not shared state
// features/checkout/hooks/useCheckoutComplete.ts
export function useCheckoutComplete() {
  return useMutation({
    mutationFn: submitOrder,
    onSuccess: (order) => {
      emit("checkout:completed", { orderId: order.id, total: order.total });
      // Cart feature listens to this event and clears itself
      // No direct dependency between checkout and cart
    },
  });
}

// ANTI-PATTERN
// A page component that fetches, transforms, and renders everything.
// Untestable in isolation. Impossible for multiple teams to contribute to.
// Every change to any part risks breaking the whole.
export default function ShopPage() {
  const [products, setProducts] = useState([]);
  const [cart, setCart] = useState([]);
  const [user, setUser] = useState(null);
  const [filters, setFilters] = useState({});
  const [checkoutOpen, setCheckoutOpen] = useState(false);
  // ... 300 lines of interleaved fetch, state, and render logic
}

// CORRECT: Page as composition of owned feature modules
// app/(shop)/page.tsx
export default function ShopPage() {
  // Page owns layout and orchestration only
  // Each feature module is independently tested and owned
  return (
    <ShopLayout>
      <SearchBar />       {/* catalog-team */}
      <ProductFilters />  {/* catalog-team */}
      <ProductGrid />     {/* catalog-team */}
      <CartDrawer />      {/* cart-team */}
    </ShopLayout>
  );
}

// ANTI-PATTERN
// features/cart/hooks/useCart.ts
import { useProducts } from "@/features/catalog/hooks/useProducts"; // cart -> catalog

// features/catalog/components/ProductCard.tsx
import { useCartItem } from "@/features/cart/hooks/useCart"; // catalog -> cart

// This circular dependency means:
// - Neither feature can be built without the other
// - Changes to either feature can unexpectedly affect the other
// - Testing either feature in isolation requires mocking the other

// CORRECT: Break the cycle with domain events or props
// features/catalog/components/ProductCard.tsx
interface ProductCardProps {
  product: CatalogProduct;
  onAddToCart?: (productId: string) => void; // behavior injected by page
}

// features/cart/hooks/useCart.ts
// Subscribes to domain events instead of importing from catalog
useEffect(() => {
  return on("catalog:add-to-cart", ({ productId, quantity }) => {
    addItem({ productId, quantity });
  });
}, []);

// ANTI-PATTERN
// packages/ui/src/components/Button.tsx
// Renamed prop without deprecation or codemod.
// Breaks 47 usages across 4 apps silently (TypeScript will catch it, but CI
// for consuming apps was not run, so the merge went through).

// Before:
interface ButtonProps { variant: "primary" | "secondary" }

// After (breaking change released as a patch):
interface ButtonProps { appearance: "primary" | "secondary" } // renamed without warning

// CORRECT: Follow the deprecation lifecycle
// Step 1: Add new prop, deprecate old (minor version)
interface ButtonProps {
  /** @deprecated Use 'appearance' instead. Will be removed in v3.0.0. */
  variant?: "primary" | "secondary";
  appearance?: "primary" | "secondary";
}

// Step 2: In the component, accept both with a dev-only warning
const resolvedAppearance = appearance ?? variant;
if (process.env.NODE_ENV === "development" && variant !== undefined) {
  console.warn("[ui] Button: 'variant' prop is deprecated. Use 'appearance'.");
}

// Step 3: Run codemod across the monorepo as part of the deprecation PR
// Step 4: Remove 'variant' in the next major version

# Create an Nx workspace with multiple Vite apps
# npm
npx create-nx-workspace@latest my-org --preset=react-monorepo --framework=react --bundler=vite
# yarn
yarn create nx-workspace@latest my-org --preset=react-monorepo --framework=react --bundler=vite

# Add a new application to an existing workspace
npx nx generate @nx/react:app apps/admin --bundler=vite --routing=true
# or: yarn nx generate @nx/react:app apps/admin --bundler=vite --routing=true

# Generate a shared library
npx nx generate @nx/react:lib packages/ui --buildable --publishable --importPath=@my-org/ui
# or: yarn nx generate @nx/react:lib packages/ui --buildable --publishable --importPath=@my-org/ui

# Run only affected tests (key CI performance advantage over Turborepo)
npx nx affected -t test --base=main
# or: yarn nx affected -t test --base=main

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": { "dependsOn": ["^build"], "cache": true },
    "test": { "cache": true },
    "lint": { "cache": true }
  },
  "generators": {
    "@nx/react": {
      "library": { "linter": "eslint", "unitTestRunner": "vitest" },
      "application": { "linter": "eslint", "e2eTestRunner": "playwright" }
    }
  }
}

{
  "name": "ui",
  "tags": ["scope:shared", "type:ui"],
  "targets": {
    "build": { "executor": "@nx/vite:build" },
    "test": { "executor": "@nx/vite:test" }
  }
}

// .eslintrc.json — enforce the tag-based boundary rules
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "depConstraints": [
          {
            "sourceTag": "scope:catalog",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:catalog"]
          },
          {
            "sourceTag": "scope:checkout",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:checkout"]
          },
          {
            "sourceTag": "type:app",
            "onlyDependOnLibsWithTags": ["type:ui", "type:util", "type:data-access"]
          }
        ]
      }
    ]
  }
}

import { createRouter, createRoute, createRootRoute, lazy } from "@tanstack/react-router";

const rootRoute = createRootRoute({ component: AppShell });

// Lazy-loaded MFE routes — each remote app owns its route subtree
const catalogRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/catalog",
  component: lazy(() =>
    import("catalog/CatalogApp").then((m) => ({ default: m.CatalogApp }))
  ),
});

const checkoutRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/checkout",
  component: lazy(() =>
    import("checkout/CheckoutApp").then((m) => ({ default: m.CheckoutApp }))
  ),
});

export const router = createRouter({
  routeTree: rootRoute.addChildren([catalogRoute, checkoutRoute]),
});