ddd-application-slice

Files (4)

• README.md
• SKILL.md
• evals.json · evals/
• slice-planning-checklist.md · references/

SKILL.md (first lines)

## Purpose

Use this skill to design or implement one coherent DDD application slice in a standardized structure:

- entrypoint (`controller`, `endpoint`, or `application service`)
- mediator-style message (`query`, `command`, or `event`/fire-and-forget message)
- handler
- optional domain service
- repository and mapping

Keep the skill technology-agnostic. The mediator library can vary. Preserve the architectural responsibilities.

## Core model

Treat each new use case as one of these three flows:

1. **Query for data**
   - use a request/response read model such as a query + query handler
   - keep it side-effect free
   - usually inject repository directly in the handler and map/return the result

2. **Trigger a change and wait for a result**
   - use a command-style request handled synchronously from the caller's perspective
   - return only the data the caller actually needs
   - for simple changes, handler-to-repository is acceptable
   - for business rules, orchestration, invariants, or multi-entity logic, call a domain service that uses repositories

3. **Trigger a change and do not wait for a result**
   - use an event, notification, local message, queued command, or equivalent fire-and-forget concept from the chosen stack
   - use this for follow-up work, integration reactions, notifications, cache invalidation, workflows, or other side effects that should not shape the immediate response contract

## Workflow

### 1. Identify the entrypoint

Start from the caller-facing surface:

- controller
- HTTP endpoint
- application service
- background entrypoint

Keep the entrypoint thin.

It should mainly:

- accept input
- enforce coarse authorization or transport concerns if needed
- create the mediator message
- dispatch it
- return the result

Do not place business rules or repository orchestration in the entrypoint unless the existing project convention explicitly requires it.

### 2. Choose the message type before writing code

Ask:

- Is this only reading data? Use a **query**.
- Is this changing state and the caller needs completion or returned data? Use a **command**.
- Is this changing state or reacting to a change without the caller waiting for completion? Use an **event** or other fire-and-forget message.

If a single request both mutates state and kicks off secondary reactions, split the responsibilities:

- command handles the primary state change
- event or fire-and-forget message handles follow-up reactions

### 3. Design the handler responsibilities

Handlers should coordinate one use case, not become a dumping ground.

Default handler responsibilities:

- load required data
- perform simple guard checks that are specific to the use case
- map transport DTOs to domain/application models where needed
- delegate business logic to the right place
- persist through repositories, directly or via domain service
- map the result to the response type
- publish follow-up events when appropriate

### 4. Decide between direct repository usage and domain service

Use this default decision rule:

**Use repository directly from the handler when** the action is simple, localized, and has little business logic.

Examples:

- straightforward lookup
- simple create, update, or delete
- toggling or saving user preferences
- fetching and mapping data for a query

**Use a domain service when** the use case includes meaningful business behavior.

Typical signals:

- invariants or business rules
- multiple validation steps
- multiple entities or aggregates involved
- workflow or stage transitions
- derived values or generated identifiers
- repeated logic likely to be reused
- domain events or follow-up reactions tied to domain behavior

The preferred chain for complex writes is:

`entrypoint -> mediator message -> handler -> domain service -> repository`

### 5. Shape the output deliberately

For queries:

- return DTOs or read models
- optimize for read concerns and mapping clarity
- do not return domain entities directly unless the project standard explicitly does so

For commands:

From Linksofteu/LinkSoft_Skills, MIT.

More from Linksofteu/LinkSoft_Skills