Diablo_ClaudeMD_Ricing_example/skills/tdd/references/layer_guide.md

DDD / Onion Layer Reference

Compact reference for layer-aware TDD. Not a DDD textbook — just enough for agents to enforce dependency direction and choose the right test strategy.

Why This Matters (Research-Backed)

• AI-generated code without architectural constraints produces 80% dependency violation rates in hexagonal architecture (arXiv:2512.04273, 2025). Layer constraints in agent prompts directly counteract this.
• Static tools detect only ~77% of dependency violations on average (Pruijt et al., 2017). Our refactorer supplements tooling by checking imports + transitive deps during code review.
• Test-driven prompting improves LLM code generation accuracy by 38-45% (Naik et al., 2024). RED-first with focused prompts is empirically better than spec-first.
• TDD alone doesn't automatically improve design (Turhan et al., 2017). The REFACTOR phase with dependency checks is essential, not optional — it's where architectural quality emerges.

Layer Definitions (Inside → Outside)

Domain Model (Core)

• Entities, Value Objects, Aggregates, Domain Events
• ZERO external dependencies (no ORM, no HTTP, no frameworks)
• Test with: direct construction, no mocks
• Example: User entity with email validation, Money value object with currency math

Domain Services

• Complex operations spanning multiple aggregates
• Depends on: Domain Model only (+ interfaces for ports it needs)
• Test with: real domain objects, in-memory fakes for repository interfaces
• Example: RegistrationService checking uniqueness via a repository interface

Application Services (Use Cases)

• Orchestrate domain logic, handle transactions, coordinate side effects
• Depends on: Domain Model + Domain Services
• Defines port interfaces that infrastructure will implement
• Test with: in-memory fakes for all ports/repositories
• Example: RegisterUserUseCase coordinating validation, persistence, email notification

Infrastructure & Presentation

• DB access, external APIs, controllers, CLI handlers, adapters
• Depends on: all inner layers (implements their interfaces)
• Test with: integration tests, may use real dependencies or test containers
• Example: PostgresUserRepository implementing UserRepository interface

Port Interface Placement

Ports (interfaces that abstract external dependencies) are defined by the layer that consumes them, not the layer that implements them:

• A UserRepository interface consumed by a domain service lives in domain/ports/ or domain-service/ports/
• A NotificationService interface consumed by an application use case lives in application/ports/
• Infrastructure implements these interfaces but never defines them

Rule: the consumer defines the contract; the provider fulfills it. This is the Dependency Inversion Principle.

Dependency Rule

Dependencies flow INWARD only. Inner layers define interfaces (ports); outer layers implement them (adapters).

Infrastructure → Application → Domain Services → Domain Model
     ↓               ↓               ↓                ↓
  implements     orchestrates     uses real        pure logic
  interfaces     via ports        domain objects   no imports

Violation example: domain/user.py importing from infrastructure.db import Session — domain must never import infrastructure.

Layer Detection Heuristics

When classifying a slice, ask:

1. Does it involve only business rules with no I/O? → domain
2. Does it coordinate multiple domain objects but still no I/O? → domain-service
3. Does it orchestrate a workflow (validate, persist, notify)? → application
4. Does it talk to a database, HTTP API, file system, or framework? → infrastructure

Test Strategy by Layer

Layer	Mocks/Fakes	Framework imports	I/O allowed
domain	None	None	No
domain-service	In-memory fakes for ports	None	No
application	In-memory fakes for all ports	Minimal (DI container)	No
infrastructure	Optional (real deps or test containers)	Yes	Yes