ddd

Domain-Driven Design - Strategic Guide

Persona

Read .claude/roles/architect.md — adopt this profile and follow all its rules.

Activation

This skill activates for high-level domain decisions:

• Splitting into Bounded Contexts
• Defining the Ubiquitous Language
• Creating a new business module
• Analyzing relationships between contexts

Important clarification

Clean Architecture definitions take precedence over DDD tactical definitions.

We use DDD only at the strategic level (domain splitting, language). Tactical patterns (Entities, Use Cases, Gateways, Presenters) follow Clean Architecture.

What we take from DDD	What we do NOT take
Bounded Contexts	Aggregates
Ubiquitous Language	Repositories (we have Gateways)
Context Mapping	Domain Events
Module splitting	Complex Value Objects

---

Bounded Context

"A Bounded Context delimits the applicability of a particular model." — Eric Evans

A Bounded Context = a module in modules/<context-name>/

Each BC is an autonomous package with its own public API.

Identifying a Bounded Context

Signs that a new BC is needed:

• The same term has different meanings depending on context
• A different team could manage this part
• The model is becoming too complex
• Business rules are diverging

ReviewFlow example:

Bounded Context	Responsibility
review	Code review orchestration and result handling
tracking	MR/PR assignment tracking and follow-up
webhook	Inbound webhook processing (GitLab/GitHub)
mcp	Model Context Protocol server and tools
dashboard	Review statistics and visualization
security	Secret detection and access control

---

Communication between Bounded Contexts

BCs communicate via their public APIs, like two independent packages.

// modules/tracking/index.ts (public API)
export { TrackAssignmentUseCase } from "./application/usecases/trackAssignment.usecase"
export { createTrackedMr } from "./domain/factories/trackedMrFactory"
export type { TrackingGateway } from "./application/ports/gateways/trackingGateway"

// modules/review/ imports from the public API
import { TrackAssignmentUseCase } from "@/modules/tracking"

Communication rules

Allowed	Forbidden
Import from another BC's index.ts	Directly import an internal file
Pass data (DTO, primitives)	Share mutable entities
Call an exposed Use Case	Access internal state

Concrete example

// modules/review/application/usecases/triggerReview.usecase.ts
import { TrackAssignmentUseCase } from "@/modules/tracking"  // Public API

export const triggerReview = async (data) => {
  const trackAssignment = new TrackAssignmentUseCase(trackingGateway);
  // ...
}

// FORBIDDEN - internal import
import { parseTrackingData } from "@/modules/tracking/domain/validators/trackingValidator"

---

Ubiquitous Language

"Use the model as the backbone of a language." — Eric Evans

Business vocabulary must be:

• Consistent: same term = same concept within a given context
• Explicit: no ambiguity
• Shared: understood by devs AND business stakeholders

In code

// Ubiquitous Language respected
class ReviewContext { ... }
class TrackedMr { ... }
function triggerReview() { ... }
function trackAssignment() { ... }

// Technical or ambiguous vocabulary
class Data { ... }           // "Data" is not a business term
class ReviewRequest { }      // "Request" vs "ReviewContext"?
function doReview() { }      // "do" vs "trigger"?

Language documentation

Each BC maintains its glossary in /docs/business/glossary/<context>.md

# Glossary - Review

| Term | Definition |
|------|------------|
| ReviewContext | The full context for a code review (diff, MR metadata, threads) |
| TrackedMr | A merge request being tracked for review assignments |
| ReviewAction | An action to perform on the platform (comment, resolve, reply) |
| DiffMetadata | Parsed metadata from a merge request diff |

---

Workflow: Creating a new Bounded Context

Step 1: Identify the domain

DDD - Identification

New domain identified: [name]

Questions to validate:
1. What business problem does it solve?
2. What are the specific terms?
3. What are the main entities?
4. Which existing BCs will use it?

Shall we explore these questions?

Step 2: Define the language

DDD - Ubiquitous Language

Proposed glossary for [context]:

| Term | Definition |
|------|------------|
| ... | ... |

Are these terms aligned with the business vocabulary?

Step 3: Define the public API

DDD - Public API

Planned exports for [context]:

Entities: [list]
Use Cases: [list]
Types: [list]

Which other BCs will consume this API?

Step 4: Create the structure

DDD - Structure

I will create:
modules/[context]/
├── index.ts           # Public API
├── entities/
├── use-cases/
├── interface-adapters/
└── testing/

+ Glossary: docs/business/glossary/[context].md

Shall we create this structure?

After validation -> Switch to the Architecture skill for tactical details.

---

Anti-patterns to avoid

• A single catch-all "domain" module
• Mixing vocabulary from multiple contexts
• Circular dependencies between contexts
• Importing internal files from another BC
• Naming modules by technical aspect ("services", "models")

---

References

• Domain-Driven Design (Eric Evans, 2003) - Chapters 1-4 (strategic)
• For tactical patterns -> see architecture skill (Clean Architecture)