Our review

This skill provides a Domain-Driven Design (DDD) architecture for structuring Python applications, using tactical patterns such as Domain Model, Repository, Service Layer, Unit of Work, and Aggregates.

Strengths

Clearly separates business logic from infrastructure, improving maintainability and testability.
Offers proven patterns and a shared language for teams dealing with complex domains.
Includes a decision framework for placing services in multi-service architectures.

Limitations

Can be overkill for simple applications or CRUD operations with little business logic.
Requires a good understanding of the domain to model aggregates and entities correctly.
Python-specific; may need adaptation for other languages or frameworks.

When to use it

Use this skill when your Python application involves complex business rules, needs clear separation between logic and data access, or when architecting a new service or module.

When not to use it

Avoid this skill if your project is a quick prototype, a simple API without business logic, or if the team is unfamiliar with DDD concepts.

Examples

Designing an Order Management Service

I'm building a new microservice for order management. Help me apply DDD patterns: define the domain model (Order, OrderLine, Money), a repository for persistence, a service layer for use cases like placeOrder, and a unit of work for transaction control. Use Python and keep infrastructure separate from business logic.

Refactoring Leaky Architecture

Review this Python codebase for business logic leakage into the data layer. Suggest refactoring to use repository and domain model patterns, ensuring all business rules stay in the domain and dependencies point inward.

name: arch-ddd description: Tactical DDD patterns for clean Python architecture including Domain Model, Repository, Service Layer, Unit of Work, and Aggregates. Use for backend architecture decisions, implementing data access layers, separating business logic from infrastructure, or reviewing code separation. allowed-tools: Read, Grep, Glob

Domain-Driven Architecture

Architectural patterns for building maintainable Python applications with clean separation between business logic and infrastructure.

Core Principle

"Behavior should drive storage, not the reverse." Focus on what the system does, not just its data model.

The Four Pillars

1. Domain Model Pattern

The heart of your application - pure business logic, no infrastructure dependencies.

Entities: Objects with long-lived identity (User, Order)
Value Objects: Immutable, defined by attributes (Money, Address)
Domain Services: Logic spanning multiple entities

2. Repository Pattern

Abstraction over persistent storage with simple interface.

Decouple domain from data access
Enable testing with fake implementations
Hide persistence complexity

3. Service Layer Pattern

Orchestrates use cases and defines application boundaries.

Thin orchestration, not business logic
Handles transaction boundaries
Clear API for use cases

4. Unit of Work Pattern

Atomic operations and transaction lifecycle management.

Explicit transaction boundaries
Single entry point to repositories
Ensures consistency

Aggregate Pattern

Consistency boundaries - clusters of objects that must remain consistent together.

One aggregate = one repository
Modify one aggregate per transaction
Reference others by ID only

The Dependency Rule

Dependencies point inward:

Entrypoints → Service Layer → Domain Model
     ↓              ↓
  Adapters ← ← ← ← ←

When to Apply

| Scenario | Pattern | |----------|---------| | Complex business rules | Domain Model | | Multiple data sources | Repository | | Multiple entry points | Service Layer | | Transaction management | Unit of Work | | Complex invariants | Aggregates |

Multi-Service Architecture

Service Placement Decision Framework

When deciding where to place new features, domain ownership typically outweighs infrastructure convenience.

Decision criteria (priority order):

Domain Ownership - Which service owns the business capability?
Data Ownership - Which service owns the authoritative data?
Infrastructure Reuse - Which service has needed infrastructure already?
Deployment Coupling - Which choice minimizes cross-service deployments?

Example: | Option | Domain | Data | Infrastructure | Decision | |--------|--------|------|----------------|----------| | gateway-service | ❌ (real-time) | ❌ | ✅ (has DB) | Reject | | migrations-service | ❌ (schemas) | ❌ | ✅ (has batch) | Reject | | analytics-service | ✅ (analytics) | ✅ (owns data) | ❌ (needs new) | Accept |

Trade-off: Infrastructure setup is one-time cost; wrong service boundaries compound over time.

See reference.md for detailed explanations and examples.md for implementations.

Domain-Driven Architecture Patterns

Recommended for