angular-ddd

angular-ddd

Domain-Driven Design guidance for Angular/TypeScript domain code. Makes DDD principles explicit and enforceable for the coder and code-reviewer agents.

When to Activate

• Creating or modifying domain models (entities, value objects, aggregates)
• Adding repositories, factories, or domain services
• Defining or refactoring bounded contexts
• Reviewing domain code for DDD compliance
• Refactoring anemic models toward rich behavior
• Enforcing aggregate invariants or encapsulation rules

Provenance

Content is synthesized from established DDD literature:

• Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software (2003) — "Blue Book"
• Vaughn Vernon, Implementing Domain-Driven Design (2013) — "Red Book"
• Martin Fowler, bliki articles on Anemic Domain Model, Domain Event, etc.
• TypeScript-specific idioms: branded types, discriminated unions, readonly, Object.freeze

This is a practitioner synthesis, not a verbatim reproduction. Where sources disagree, the Red Book's pragmatic guidance takes precedence for implementation details.

Core Principles

1. The domain model is the software. Business logic lives in domain objects and pure functions, not in services or components. (Evans, ch. 1)
2. Ubiquitous Language. Code names match the domain expert's vocabulary. No translation layer between business and code. (Evans, ch. 2)
3. Bounded Contexts define boundaries. Each context owns its model. Shared types across contexts are a design smell. (Evans, ch. 14)
4. Aggregates enforce invariants. All mutations go through the aggregate root. External code never reaches inside. (Vernon, ch. 10)
5. Value Objects are immutable and identity-free. They describe characteristics, not things. (Evans, ch. 5)
6. Repositories return aggregates, not tables. Persistence is an infrastructure concern. (Vernon, ch. 12)

TypeScript Idioms

The Angular-specific delta vs. the .NET DDD skill:

Concept	.NET idiom	TypeScript idiom
Identity	CustomerId record struct	Branded type: type CustomerId = string & { readonly __brand: 'CustomerId' }
Immutability	readonly record struct	readonly props + Object.freeze() for VOs; ReadonlyArray<T> for collections
Domain events	sealed record : IDomainEvent	Discriminated union with readonly kind discriminant
Domain model	sealed class with private setters	type alias with readonly props (per [[angular-clean-architecture]] convention)
Domain rules	Static methods on entity	Pure exported functions in core/rules/
Ports	interface in Core	abstract class with abstract methods returning Observable<T> (per [[angular-clean-architecture]] convention)
Equality	Equals/GetHashCode override	Structural: compare all fields; identity: compare id field