Mastering Domain-Driven Design & Hexagonal Architecture in Modern Web Apps

Why Domain Independence Matters

In Domain-Driven Design (DDD) paired with Hexagonal Architecture (Ports and Adapters), the domain model is the heart of the software. It must remain completely free of framework imports, ORM annotations, or database driver specifics.

Key Architectural Rules

1. Repository Interfaces in Domain: Always place repository contracts in domain/repository/, never in application/port/out/.

2. External Service Ports: Use application/port/out/ strictly for external adapters such as JWT token signing, password hashing, email delivery, or payment gateways.

3. Use Case Orchestration: Application use cases coordinate domain entities and domain repositories, returning clean Result DTOs via dedicated mappers.

// Clean Use Case Pattern
export class CreatePostUseCaseImpl implements CreatePostUseCase {
  constructor(
    private readonly postRepository: PostRepository,
    private readonly categoryRepository: CategoryRepository
  ) {}
}

By enforcing these boundaries, migrating between storage engines—or running sub-millisecond unit tests—requires zero changes to domain logic.