ddd

name	ddd
description	Domain Driven Design guidance for TypeScript/Deno codebases. Apply when writing or modifying code to choose appropriate DDD building blocks (entities, value objects, aggregates, domain services, repositories) and maintain ubiquitous language. Triggers on all code changes to ensure domain model consistency.

Domain Driven Design

Apply these patterns when implementing domain logic in TypeScript/Deno.

Building Block Selection

Choose the appropriate type based on these criteria:

Type	Identity	Mutability	When to Use
Value Object	None (equality by value)	Immutable	Measurements, descriptions, identifiers, money, dates, addresses
Entity	Has unique ID	Mutable	Things with lifecycle, tracked over time, referenced by ID
Aggregate	Root entity + children	Root controls mutations	Consistency boundary, transactional unit, enforce invariants
Domain Service	None	Stateless	Operations spanning multiple aggregates, external integrations
Repository	None	Stateless	Persistence abstraction for aggregates only
Application Service	None	Stateless	Orchestrate domain objects for a use case; own the transaction boundary; return results or emit progress events; live in the application/libswamp layer, not the domain

Quick Decision Flow

Does it have a unique identity that matters?
├─ No → Value Object
└─ Yes → Does it enforce invariants over child objects?
         ├─ Yes → Aggregate Root
         └─ No → Entity (likely part of an aggregate)

Does it orchestrate multiple domain objects for a use case?
└─ Yes → Application Service (lives in the application/libswamp layer)

TypeScript Patterns

See references/patterns.md for implementation examples.

Ubiquitous Language

Update the project's ubiquitous language glossary when:

• New domain concept introduced (add term + definition)
• Meaning clarified through discussion (refine definition)
• Naming conflicts discovered (resolve and document)
• Bounded context boundary identified (note context for term)

Location: Document terms in code via types/interfaces. Add non-obvious terms to project documentation.

Naming Rules

• Use domain expert terminology, not technical jargon
• Prefer nouns for entities/value objects: Order, Money, Address
• Prefer verbs for domain services: PricingService, ShippingCalculator
• Name aggregates by their root: Order (not OrderAggregate)

Anti-Patterns to Avoid

• Anemic domain model: Entities with only getters/setters, logic in services
• God aggregate: Too many entities under one root (split by invariant boundary)
• Repository per entity: Only aggregate roots get repositories
• Leaking persistence: Domain objects should not know about storage