clean-architecture

Clean Architecture

Strategic architecture principles for boundaries, dependencies, and layered system design.

When to Use

• Designing service boundaries or module structure
• Evaluating dependency direction and circular dependencies
• Structuring new applications or refactoring monoliths
• Assessing where to place entities, use cases, adapters, and frameworks
• Deciding when to introduce architectural boundaries

When Not to Use

• Class-level design decisions (use solid-principles)
• Choosing structural patterns like Factory or Adapter (use design-patterns)
• Testing strategy configuration (use testable-design)

Architecture Layers

Dependency Rule: Dependencies point inward only. Inner layers know nothing about outer layers.

Layers (inner → outer): Entities → Use Cases → Interface Adapters → Frameworks & Drivers

See references/dep-inward-only.md for layer definitions and examples.

Workflow

Step 1: Identify Decision Type

Output: Classify as entity, use case, adapter, or framework decision.

Ask:

• Does this logic belong to core business rules? → Entity
• Does it orchestrate business workflows? → Use Case
• Does it translate between layers? → Adapter
• Is it external infrastructure? → Framework

Step 2: Apply Dependency Direction Checks

Output: Dependency violations with corrective actions.

Checklist:

• Dependencies point inward (no outer layers importing inner layers)
• No circular dependencies between modules
• Clear ownership of interfaces (defined by inner layers, implemented by outer layers)
• Entities remain pure (no framework or infrastructure imports)

Example:

Violation: Entity imports ORM decorator from infrastructure.
Refactor: Define entity as plain object; map to ORM in repository (adapter layer).

Step 3: Design Use Cases

Output: Use case interface with input/output ports.

Template:

// Use Case (application layer)
interface CreateOrderUseCase {
  execute(input: CreateOrderInput): Promise<CreateOrderOutput>
}

// Input/Output ports (defined by use case)
interface CreateOrderInput {
  userId: string
  items: OrderItem[]
}

interface CreateOrderOutput {
  orderId: string
  status: string
}