monorepo-architecture

name	monorepo-architecture
description	TypeScript monorepo structure - module boundaries, dependency direction, god objects, abstraction discipline, configuration management, interface design. Use when creating packages, refactoring cross-package imports, or reviewing architecture.
keywords	monorepo, module boundaries, circular dependency, barrel file, god object, feature envy, abstraction, Rule of Three, composition over inheritance, configuration, dependency management, workspace protocol, interface design, options object, Clean Architecture, SOLID
related	error-handling-patterns, typescript-type-safety, domain-driven-design, safe-refactoring, dependency-injection-patterns

Monorepo Architecture Patterns

Production-grade rules for TypeScript monorepos with 15+ packages. Covers module boundaries, class design, abstraction discipline, config management, dependency hygiene, and interface design.

Reference: docs/deepresearch/reports/TypeScript Monorepo Architecture Patterns.md

Non-Negotiable Rules

#	Rule	Rationale
1	Dependencies point inward only (infra -> application -> domain)	Prevents circular deps; enables independent deployment
2	Public API = package index.ts only; no deep imports (@pkg/foo/internal/bar)	Encapsulation; safe refactoring
3	No circular dependencies between packages	Use madge --circular or depcruise to detect
4	No barrel files with export * (the "barrel of death")	Defeats tree-shaking; hides coupling
5	Classes <= 500 LOC, <= 20 public methods	God object = split by SRP
6	Rule of Three: abstract on 3rd identical occurrence, not before	Wrong abstraction is 5-10x costlier than duplication
7	One validated config object per app; parse at startup, never at import time	Fail fast; typed; single source of truth
8	process.env in <= 1 file per package (config module)	Scattered env reads = untraceable config
9	Functions with >4 params -> options object	Readable callsites; easy extension
10	Internal packages use workspace:*; external deps only if >200 LOC to implement	Controls dependency surface

Pattern 1: Module Boundaries

WRONG - UI depends on core, circular imports, barrel of death

// packages/ui/Button.tsx
import { apiClient } from '@myapp/core';   // UI -> core (wrong direction)
import { User } from '@myapp/domain';      // leaks domain into UI

// packages/core/api.ts
import { Button } from '@myapp/ui';        // circular!

// packages/shared/index.ts
export * from './utils';   // barrel of death - re-exports everything
export * from './types';
export * from './constants';

CORRECT - Layered architecture with dependency inversion

// packages/domain/user.ts (public interface - innermost layer)
export interface UserRepository {
  findById(id: string): Promise<User>;
}

// packages/infra/user-repo-impl.ts (concrete, depends only on domain)
import type { UserRepository } from '@myapp/domain';
export class PostgresUserRepo implements UserRepository { ... }

// packages/ui/Button.tsx (depends only on application layer abstractions)
import { useUser } from '@myapp/application';

Ownership rule: A package belongs where its abstraction lives. Concrete implementations go in the outer layer.

Smells: >5 cross-package imports in one file; any export * barrel.

Pattern 2: God Objects & Feature Envy

WRONG - One class doing everything

class UserService {  // ~800 LOC, 6 different concerns
  getUser(id: string) { ... }
  saveUser(user: User) { ... }
  sendWelcomeEmail(user: User) { ... }        // EmailService's job
  calculateLifetimeValue(user: User) { ... }  // Billing's job
  formatUserForUI(user: User) { ... }         // UI layer's job
}

CORRECT - Single Responsibility, Tell-Don't-Ask

// application/user-service.ts (only registration concern)
export class UserService {
  constructor(
    private repo: UserRepository,
    private email: EmailService,
  ) {}
  async register(userData: CreateUserDto) { ... }
}

// Separate services own separate concerns
await emailService.sendWelcome(newUser);
await billingService.recordLifetimeValue(newUser);

Feature Envy test: Does the method use >50% of data/methods from another object? Move it there.

Refactoring sequence: (1) Identify envied methods -> Move Method, (2) Extract Class for clusters, (3) Introduce facade for callers during migration.

Pattern 3: Abstraction Discipline (Rule of Three)

WRONG - Premature abstraction

// Only 2 implementations -> forced hierarchy
abstract class BasePaymentProcessor {
  protected abstract validate(...): void;
  protected abstract charge(...): void;
}
class StripeProcessor extends BasePaymentProcessor { ... }
class PaypalProcessor extends BasePaymentProcessor { ... }
// New requirement breaks hierarchy -> boolean flags everywhere

CORRECT - Duplicate first, abstract on third occurrence

// 1st and 2nd use: just duplicate the function
const formatCurrency = (amount: number, locale: string) => ...;

// 3rd identical use: NOW extract a module with a domain name
export const money = {
  format: (amount: number, locale = 'en-US') => ...,
  parse: (raw: string) => ...,
};

Decision framework:

• Can't name the abstraction with a clear domain term? -> Duplicate.
• Business concept used in >=3 places with same variation points? -> Abstract.
• Uncertain? -> Duplicate. Wrong abstraction costs 5-10x more.

Smells: Boolean params that change behavior (process(..., isRecurring: boolean)); inheritance depth >2; abstract classes with <=2 concrete subclasses.

Pattern 4: Configuration Management

WRONG - Scattered process.env reads

// 15 different files, each reading env directly
const apiUrl = process.env.API_URL ?? 'https://default.com';
const dbUrl = process.env.DATABASE_URL!;  // no validation, ! assertion

CORRECT - Single validated config at startup

// packages/config/src/schema.ts
import { z } from 'zod';

export const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  DATABASE_URL: z.string().url(),
  STRIPE_SECRET: z.string().min(1),
});

export type Config = z.infer<typeof configSchema>;

// packages/config/src/index.ts
const raw = { ...process.env, ...loadEnvFile() };
export const config = configSchema.parse(raw); // fails fast at startup

Already enforced in AegisCore: See config.ts pattern in CLAUDE.md rule #3. This pattern reinforces why: fail-fast at startup, not at runtime when a missing var is first accessed.

Pattern 5: Dependency Management

WRONG - Uncontrolled dependencies

{
  "dependencies": {
    "lodash": "^4.17.21",     // 300KB for one function
    "moment": "^2.30.1",      // deprecated, use date-fns
    "left-pad": "^1.3.0"      // 5 lines to implement
  }
}

CORRECT - Minimal, workspace-aware

{
  "dependencies": {
    "@aegis/domain": "workspace:*",
    "@aegis/config": "workspace:*",
    "zod": "^3.23.8",
    "date-fns": "^3.6.0"
  }
}

Add a dependency only if: (1) battle-tested and solves real pain, OR (2) implementing yourself would exceed ~200 LOC + ongoing maintenance.

Smells: >30 direct deps per package; duplicate transitive deps (bun pm ls shows duplicates); version drift across packages for same library.

Pattern 6: Interface Design

WRONG - Long parameter lists

function processPayment(
  amount: number,
  userId: string,
  currency: string,
  isRecurring: boolean,
  discountCode?: string,
  metadata?: Record<string, any>,
  onSuccess?: () => void,
) { ... }

CORRECT - Options object for 4+ params

interface ProcessPaymentOptions {
  amount: number;
  userId: string;
  currency?: string;          // sensible default
  isRecurring?: boolean;
  discountCode?: string;
  metadata?: Record<string, unknown>;  // unknown > any
  onSuccess?: () => void;
}

function processPayment(options: ProcessPaymentOptions) { ... }

Threshold: <=3-4 positional params is fine. >4 -> options object. Builder pattern only for step-wise validation with many optional fields (rare in TS).

Smells: >5 parameters; multiple boolean flags; inconsistent naming across codebase (getUser vs fetchUserData).

Common Anti-Patterns Checklist

Before submitting code, verify:

• No circular dependencies between packages (run madge --circular mentally)
• No deep imports past a package's index.ts
• No export * barrels
• No class >500 LOC or >20 public methods
• No premature abstractions (Rule of Three satisfied?)
• No process.env reads outside config module
• No functions with >4 positional parameters
• Internal packages use workspace:*
• Dependencies point inward (infra -> app -> domain)
• New dependency justified (>200 LOC to implement?)

See Also

• [[error-handling-patterns]] - Error handling within and across package boundaries
• [[typescript-type-safety]] - Type safety fundamentals (unknown vs any, import type, satisfies, generics)
• [[domain-driven-design]] - DDD strategic/tactical patterns (bounded contexts, aggregates, domain events)
• [[safe-refactoring]] - Safe refactoring process (characterization tests, baby steps, Expand-Migrate-Contract, Strangler Fig)