DDD Backend Implementation - build a feature layer by layer

If the current repo has a specific implementation skill, it wins - it knows the stack, the paths and the project commands.

This skill vs. others

• This skill when: the model is settled and you write the code layer by layer (domain → application → infrastructure → handler)
• domain-modeling-design instead if: aggregates, invariants and placement are not decided yet (upstream of this skill - its output is this skill's input)
• superpowers:test-driven-development as a complement: this skill says where the code goes and in what order; TDD says how to write each layer (red test → green)

Principle

The implementation respects two non-negotiable constraints: the order of the layers (from the core outward) and the direction of dependencies (everything points toward the domain, never the reverse). The domain knows nothing of the database, the network, or the web framework. Business logic lives in the aggregates; the outer layers only adapt (parse, persist, serialize). Short-circuiting the order or inverting a dependency produces an anemic model with logic scattered around.

Context to gather (before acting)

• Framework + commands: read package.json / Cargo.toml / pom.xml / Makefile / CI config for fmt, lint, test, build
• Read one already-implemented neighboring module in the same context and copy its structure (layer split, naming, error handling, route wiring) before inventing anything
• The architecture in place: where domain / application / infrastructure / API live; how ports are declared and injected (DI, application state)
• The spec produced by the design phase (aggregates, invariants, commands/queries, ports, events) - if missing, go back to domain-modeling-design

Protocol

Implement in this order, never the reverse, never a short-circuit. Test each layer before moving to the next.

1. Domain - aggregate + invariants
   • Value object for every constrained field, never a bare primitive; validate the constraint at construction
   • Invariants validated in the aggregate's constructor / methods, nowhere else
   • Methods = domain verbs (transitions, decisions), not getters/setters
   • The domain imports nothing from infrastructure or the framework. Pure domain tests, no I/O
2. Application - CQRS + ports
   • Separate commands (mutations) and queries (reads); a query does not mutate state
   • Define the ports (interfaces) here, on the application/domain side; not their implementation
   • A command handler orchestrates: load the aggregate, call its methods, persist through the port - no business rule here
   • Queries return read DTOs, not the domain aggregate
3. Infrastructure - adapters
   • Implement the ports declared in application (repos, network clients, queues)
   • This is the only layer that depends on the concrete technology (DB, ORM, queries). Parameterized queries, never string concatenation (injection)
   • Infrastructure depends on domain/application, never the reverse
4. Handler / API - the edge
   • The handler parses input → calls the command/query → serializes output. Nothing else
   • Authn/authz and multi-tenancy handled at the edge (extractor / middleware), not in the domain
   • Document the exposed contract (OpenAPI/IDL schema) if the project generates one
5. Integration tests - from the edge down to persistence, on the happy path + at least one invariant rejection

- [ ] Domain: aggregate + value objects + invariants, pure tests green
- [ ] Application: command/query + ports, handler with no business logic
- [ ] Infrastructure: port adapters, parameterized queries
- [ ] Handler: parse → CQRS → serialize, auth at the edge
- [ ] Dependency direction verified: everything points toward the domain
- [ ] Integration tests happy path + invariant rejection
- [ ] fmt / lint / typecheck / build of the scope green

Templates

• No fixed template: copy the structure of a neighboring module in the project (local reference code beats a generic skeleton).

Traps & rationalizations

Exit condition

• All 4 layers exist in order, each tested before the next
• No business logic outside the domain (neither handler nor infra)
• Dependency direction respected: domain independent of infra and framework
• Commands and queries separated; ports in application, implementations in infra
• Integration tests green: happy path + at least one invariant rejection
• fmt / lint / typecheck / build of the scope run, output pasted - never "it should pass"

Tooling

• No generic script: the commands (fmt, lint, test, build) depend on the project, to be read from its manifest / CI config.