ddd-principles

DDD — Cross-Language OOP Principles

The rules below are language-agnostic OOP-style DDD. Language-specific examples (forbidden imports, Symbol tokens, module structure) live in:

• php-ddd-conventions (PHP / Symfony)
• nest-ddd-conventions (TypeScript / NestJS)

For functional-style DDD (immutable records, curried operations, Result pipelines), see craft:ddd-fp-principles.

1. Domain Layer Purity

The domain layer contains business logic only. Infrastructure leaks into the domain are the most common architectural violation — they make the domain untestable without the framework and impossible to reuse.

Forbidden in the Domain Layer

• Framework HTTP types (Request, Response, framework UploadedFile, etc.)
• ORM / database classes (Doctrine entities, Drizzle schemas, Prisma client)
• DI decorators / framework annotations (@Injectable, @Module, @Inject, etc.)
• Framework-specific validators
• Any external library tied to a framework

Allowed in the Domain Layer

• Pure language types (string, int, Date, plain record, etc.)
• Domain value objects (immutable, no framework dependency)
• Domain interfaces (defined in domain, implemented in infrastructure)
• Shared DTOs from contracts packages (typically packages/shared or equivalent)
• Enums / constant unions / branded types

Criterion: if the domain layer compiles WITHOUT the framework, it's pure.

2. Ports & Adapters

The boundary between domain and infrastructure is a set of interfaces (ports) defined in the domain, implemented as adapters in the infrastructure.

• Ports = pure interfaces, in the domain layer
• Adapters = concrete implementations, in the infrastructure layer
• The domain depends only on its own interfaces
• The infrastructure imports the domain — never the reverse

3. Dependency Direction (always inward)

Controllers / HTTP   →   Use Cases   →   Domain Services   →   Domain Ports
                                                                     ↑
   Infrastructure Adapters (DB, HTTP clients, …) ───────────────────┘
        (implement the domain ports)

Rule: dependencies always flow inward toward the domain. Outer layers know about inner layers; inner layers know nothing about outer layers.

4. Bounded Contexts

A bounded context is a clearly delimited part of the system with its own ubiquitous language. Each bounded context maps to a separate module / namespace / directory.

• 1 bounded context = 1 module (NestJS) / 1 namespace (PHP) / 1 directory (others)
• Bounded contexts communicate through explicit contracts (DTOs, events) — never by sharing internals

5. Aggregates

An aggregate is a state-bearing cluster of domain objects with:

• A single transactional boundary — all invariants of the aggregate must hold at commit time.
• A single aggregate root with an identity.
• External references go through the root only.

6. Value Objects

Value objects are defined by their attributes, not by an identity:

• Immutable (use readonly / final readonly / equivalent).
• Equality is by attribute equality, not by reference.
• May enforce invariants in the constructor (positive amount, valid format, etc.).

Quick Reference

Rule	Principle
Domain purity	No framework / ORM / HTTP in the domain layer
Ports & adapters	Interfaces in domain, implementations in infrastructure
Dependency direction	Always inward toward the domain
Bounded context	1 module / namespace / directory per context
Aggregate	Single transactional boundary + identified root
Value object	Immutable, equality by attributes, may enforce invariants