Domain-Driven Python Architecture

This skill enforces a domain-driven design approach for Python codebases with strict typing and self-documenting code practices.

Core Principles

This skill ensures code follows these architectural patterns:

1. **Domain-Driven Design**: Organize code around business domains rather than technical layers

2. **Strong Typing**: Use mypy-compliant type annotations on all functions

3. **Dataclasses Over Primitives**: Replace loose dictionaries and tuples with structured dataclasses

4. **Static Bundling**: Group related functions in static classes

5. **Self-Documenting Code**: Use domain-driven naming instead of comments

Instructions

When writing or reviewing Python code, follow these rules strictly:

1. Use Dataclasses and Classes Instead of Primitives

**Never use:**

**Always use:**

```python

Bad

def get_user_info() -> dict:

return {"name": "John", "age": 30}

Good

from dataclasses import dataclass

@dataclass

class UserInfo:

name: str

age: int

def get_user_info() -> UserInfo:

return UserInfo(name="John", age=30)

```

2. Bundle Domain Classes Together

Group related domain classes in dedicated modules or container classes:

```python

domain/user.py

from dataclasses import dataclass

@dataclass

class UserProfile:

username: str

email: str

@dataclass

class UserPreferences:

theme: str

notifications_enabled: bool

class UserDomain:

"""Container for user-related domain logic"""

pass

```

3. Use Static Classes to Bundle Functions

Group related functions using static methods in classes:

```python

from typing import List

class UserValidator:

@staticmethod

def is_valid_email(email: str) -> bool:

return "@" in email

@staticmethod

def is_valid_username(username: str) -> bool:

return len(username) >= 3

class UserFormatter:

@staticmethod

def format_display_name(first_name: str, last_name: str) -> str:

return f"{first_name} {last_name}"

```

4. Full Mypy Type Annotations

Every function must have complete type annotations:

```python

from typing import List, Optional, Dict, Callable

def process_users(

users: List[UserInfo],

filter_fn: Callable[[UserInfo], bool],

limit: Optional[int] = None

) -> List[UserInfo]:

filtered = [u for u in users if filter_fn(u)]

return filtered[:limit] if limit else filtered

```

5. Never Use Comments - Use Domain-Driven Naming

**Bad:**

```python

def calc(x: int, y: int) -> int:

# Calculate the total with tax

return x + (x * y / 100)

```

**Good:**

```python

def calculate_price_with_tax(base_price: int, tax_rate_percent: int) -> int:

return base_price + (base_price * tax_rate_percent / 100)

```

**Bad:**

```python

class DataProcessor:

def process(self, data: List[dict]) -> List[dict]:

# Remove invalid entries

valid = [d for d in data if d.get("status") == "active"]

# Sort by priority

return sorted(valid, key=lambda x: x.get("priority", 0))

```

**Good:**

```python

@dataclass

class ProcessableItem:

status: str

priority: int

class ActiveItemFilter:

@staticmethod

def filter_active_items(items: List[ProcessableItem]) -> List[ProcessableItem]:

return [item for item in items if item.status == "active"]

@staticmethod

def sort_by_priority_descending(items: List[ProcessableItem]) -> List[ProcessableItem]:

return sorted(items, key=lambda item: item.priority, reverse=True)

```

6. Domain Module Structure

Organize code by domain, not by technical layer:

```

src/

├── domain/

│ ├── user/

│ │ ├── entities.py # UserProfile, UserAccount dataclasses

│ │ ├── validators.py # UserValidator static class

│ │ └── formatters.py # UserFormatter static class

│ ├── order/

│ │ ├── entities.py # Order, OrderItem dataclasses

│ │ ├── calculators.py # OrderPriceCalculator static class

│ │ └── validators.py # OrderValidator static class

```

Examples

Complete Example: Order Domain

```python

from dataclasses import dataclass

from typing import List

from decimal import Decimal

@dataclass

class OrderItem:

product_id: str

quantity: int

unit_price: Decimal

@dataclass

class Order:

order_id: str

customer_id: str

items: List[OrderItem]

class OrderPriceCalculator:

@staticmethod

def calculate_subtotal(items: List[OrderItem]) -> Decimal:

return sum(item.quantity * item.unit_price for item in items)

@staticmethod

def calculate_total_with_tax(subtotal: Decimal, tax_rate: Decimal) -> Decimal:

return subtotal * (1 + tax_rate)

class OrderValidator:

@staticmethod

def has_valid_items(order: Order) -> bool:

return len(order.items) > 0

@staticmethod

def is_within_quantity_limit(order: Order, max_quantity: int) -> bool:

total_quantity = sum(item.quantity for item in order.items)

return total_quantity <= max_quantity

```

Constraints