Clean Architecture key takeaways

// src/domain/entities/User.ts
export interface User {
  readonly id: string;
  readonly email: string;
  readonly status: 'active' | 'suspended' | 'pending';
  readonly createdAt: Date;
}

export class UserFactory {
  static create(email: string): User {
    if (!email.includes('@')) {
      throw new Error('Invalid email format');
    }
    return {
      id: crypto.randomUUID(),
      email,
      status: 'pending',
      createdAt: new Date(),
    };
  }
}

// src/application/ports/IUserRepository.ts
import { User } from '../../domain/entities/User';

export interface IUserRepository {
  save(user: User): Promise<void>;
  findById(id: string): Promise<User | null>;
}

// src/application/usecases/RegisterUser.ts
import { User, UserFactory } from '../../domain/entities/User';
import { IUserRepository } from '../ports/IUserRepository';

export class RegisterUser {
  constructor(private readonly userRepository: IUserRepository) {}

  async execute(email: string): Promise<User> {
    const user = UserFactory.create(email);
 

await this.userRepository.save(user); return user; } }

**Architecture decision:** Interfaces live in the application layer, not infrastructure. This enforces the dependency rule: use cases define what they need; adapters fulfill it. The use case remains pure TypeScript with zero framework dependencies.

### Step 3: Implement Adapters (Outer Circle)
Adapters translate between external systems and application ports. Controllers, repositories, message queues, and cache clients belong here. They depend inward to implement interfaces.

```typescript
// src/infrastructure/repositories/PostgresUserRepository.ts
import { IUserRepository } from '../../application/ports/IUserRepository';
import { User } from '../../domain/entities/User';
import { Pool } from 'pg';

export class PostgresUserRepository implements IUserRepository {
  constructor(private readonly pool: Pool) {}

  async save(user: User): Promise<void> {
    await this.pool.query(
      `INSERT INTO users (id, email, status, created_at) VALUES ($1, $2, $3, $4)`,
      [user.id, user.email, user.status, user.createdAt]
    );
  }

  async findById(id: string): Promise<User | null> {
    const res = await this.pool.query(`SELECT * FROM users WHERE id = $1`, [id]);
    if (res.rows.length === 0) return null;
    return res.rows[0] as User;
  }
}

Architecture decision: Infrastructure adapters are the only layer allowed to import external libraries (pg, express, aws-sdk). They map external data shapes to domain entities. Error handling, retries, and connection pooling are isolated here.

Step 4: Compose at the Entry Point

The composition root wires dependencies. It is the only place where concrete implementations are instantiated. Frameworks bootstrap here, then delegate to use cases.

// src/composition-root.ts
import { Pool } from 'pg';
import { PostgresUserRepository } from './infrastructure/repositories/PostgresUserRepository';
import { RegisterUser } from './application/usecases/RegisterUser';

export function createApp() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const userRepository = new PostgresUserRepository(pool);
  const registerUser = new RegisterUser(userRepository);

  return { registerUser, pool };
}

Architecture decision: Composition happens once, at startup. Controllers receive pre-configured use cases. This eliminates scattered dependency injection, prevents circular dependencies, and guarantees that business logic never resolves infrastructure at runtime.

Pitfall Guide

1. Violating the Dependency Rule

Mistake: Importing framework types or database drivers into entities or use cases. Impact: Business logic becomes coupled to infrastructure. Testing requires mocks for external systems. Framework upgrades break core rules. Best practice: Run static analysis (madge, eslint-plugin-import) to block inward-to-outward imports. Keep domain and application layers free of import { ... } from 'express' or import { ... } from 'typeorm'.

2. Over-Abstracting Early

Mistake: Creating interfaces for every service, repository, and utility before a second implementation exists. Impact: Boilerplate inflation, reduced readability, and unnecessary indirection. Best practice: Apply interfaces only at system boundaries where substitution is likely (databases, message brokers, external APIs). Use concrete classes internally until a second implementation is demanded.

3. Treating Architecture as Folder Structure Without Enforcement

Mistake: Organizing code into domain/, application/, infrastructure/ folders but allowing cross-layer imports. Impact: Architecture degrades within weeks. Developers import infrastructure into use cases for convenience. Best practice: Enforce boundaries at compile time. Use TypeScript path mapping restrictions, ESLint import rules, and CI pipeline checks. Folders are documentation; tooling is enforcement.

4. Ignoring the Composition Root

Mistake: Instantiating repositories inside controllers or using service locators scattered across layers. Impact: Hidden dependencies, unpredictable lifecycles, and test setup complexity. Best practice: Centralize wiring in a single module. Pass configured use cases to adapters. Keep the composition root framework-agnostic where possible.

5. Anemic Domain Models

Mistake: Moving business logic into use cases or services while entities become passive data carriers. Impact: Logic duplication, inconsistent validation, and violation of object-oriented principles. Best practice: Keep validation, state transitions, and invariant enforcement inside entities. Use cases should orchestrate, not dictate business rules.

6. Testing the Wrong Layer

Mistake: Writing integration tests for use cases by spinning up databases and HTTP servers. Impact: Slow feedback loops, flaky tests, and blurred responsibility boundaries. Best practice: Test use cases in-process with fake repositories. Test adapters separately with real infrastructure. Reserve integration tests for boundary validation and contract compliance.

Production Bundle

Action Checklist

• Enforce dependency direction: Configure build tools to reject infrastructure imports in domain/application layers
• Centralize composition: Wire all dependencies in a single entry module before framework bootstrap
• Isolate ports: Define interfaces in the application layer; implement them in infrastructure
• Validate at creation: Move entity validation into factories or constructors; reject invalid state early
• Test boundaries separately: Unit test use cases with fakes; integration test adapters with real systems
• Audit circular dependencies: Run madge --circular weekly; refactor shared abstractions into the application layer
• Document architecture decisions: Maintain an ADR log explaining why specific ports exist and how adapters fulfill them

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup MVP (0-6 months)	Lightweight Clean Architecture (3 layers, minimal ports)	Reduces framework lock-in early while preserving velocity	+15% initial setup, -40% refactoring later
Enterprise Legacy Modernization	Strangler Fig + Adapter Layer	Wraps existing code with ports; gradually migrates logic inward	+20% overhead per module, prevents full rewrite risk
High-Compliance System (FinTech/Health)	Strict boundary enforcement + formal ADRs	Guarantees auditability, testability, and infrastructure independence	+25% design time, -60% compliance rework

Configuration Template

Folder Structure

src/
├── domain/           # Entities, value objects, domain exceptions
├── application/      # Use cases, ports (interfaces), application exceptions
├── infrastructure/   # Adapters, repositories, controllers, external clients
├── composition-root.ts
└── main.ts           # Framework bootstrap

tsconfig.json (Path & Strictness)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "paths": {
      "@domain/*": ["src/domain/*"],
      "@application/*": ["src/application/*"],
      "@infrastructure/*": ["src/infrastructure/*"]
    }
  },
  "include": ["src/**/*"]
}

ESLint Dependency Enforcement (.eslintrc.json)

{
  "plugins": ["import"],
  "rules": {
    "import/no-cycle": "error",
    "import/no-extraneous-dependencies": ["error", { "devDependencies": false }],
    "import/order": ["error", {
      "groups": ["builtin", "external", "internal", "parent", "sibling", "index"],
      "pathGroups": [
        { "pattern": "@domain/**", "group": "internal", "position": "before" },
        { "pattern": "@application/**", "group": "internal", "position": "before" },
        { "pattern": "@infrastructure/**", "group": "internal", "position": "after" }
      ],
      "newlines-between": "always"
    }]
  }
}

Quick Start Guide

1. Scaffold the boundary structure: Create domain/, application/, and infrastructure/ directories. Initialize TypeScript with strict mode and path aliases matching the template.
2. Define your first port: Write an interface in application/ports/ describing a single external dependency (e.g., IUserRepository). Do not import any database or framework types.
3. Implement a use case: Create a class in application/usecases/ that accepts the port via constructor. Write business logic using only domain entities and the port interface.
4. Wire and run: In composition-root.ts, instantiate the concrete adapter from infrastructure/, pass it to the use case, and export. Bootstrap your framework in main.ts using the exported use case. Run npm test to verify in-process execution without external dependencies.