1# Advanced Architecture Patterns — Reference
2 
3Deep-dive implementation examples for DDD bounded contexts, Onion Architecture, Anti-Corruption Layers, and full project structures. Referenced from SKILL.md.
4 
5---
6 
7## Full Multi-Service Project Structure
8 
9A realistic e-commerce system organised by bounded context, each context is a deployable service:
10 
11```
12ecommerce/
13├── services/
14│   ├── identity/                    # Bounded context: users & auth
15│   │   ├── identity/
16│   │   │   ├── domain/
17│   │   │   │   ├── entities/
18│   │   │   │   │   └── user.py
19│   │   │   │   ├── value_objects/
20│   │   │   │   │   ├── email.py
21│   │   │   │   │   └── password_hash.py
22│   │   │   │   └── interfaces/
23│   │   │   │       └── user_repository.py
24│   │   │   ├── use_cases/
25│   │   │   │   ├── register_user.py
26│   │   │   │   └── authenticate_user.py
27│   │   │   ├── adapters/
28│   │   │   │   ├── repositories/
29│   │   │   │   │   └── postgres_user_repository.py
30│   │   │   │   └── controllers/
31│   │   │   │       └── auth_controller.py
32│   │   │   └── infrastructure/
33│   │   │       └── jwt_service.py
34│   │   └── tests/
35│   │       ├── unit/
36│   │       └── integration/
37│   │
38│   ├── catalog/                     # Bounded context: products
39│   │   ├── catalog/
40│   │   │   ├── domain/
41│   │   │   │   ├── entities/
42│   │   │   │   │   └── product.py
43│   │   │   │   └── value_objects/
44│   │   │   │       ├── sku.py
45│   │   │   │       └── price.py
46│   │   │   └── use_cases/
47│   │   │       ├── create_product.py
48│   │   │       └── update_inventory.py
49│   │   └── tests/
50│   │
51│   └── ordering/                    # Bounded context: orders
52│       ├── ordering/
53│       │   ├── domain/
54│       │   │   ├── entities/
55│       │   │   │   └── order.py
56│       │   │   ├── value_objects/
57│       │   │   │   ├── customer_id.py   # NOT imported from identity!
58│       │   │   │   └── money.py
59│       │   │   └── interfaces/
60│       │   │       ├── order_repository.py
61│       │   │       └── catalog_client.py  # ACL port to catalog context
62│       │   ├── use_cases/
63│       │   │   ├── place_order.py
64│       │   │   └── cancel_order.py
65│       │   └── adapters/
66│       │       ├── acl/
67│       │       │   └── catalog_http_client.py  # ACL adapter
68│       │       └── repositories/
69│       │           └── postgres_order_repository.py
70│       └── tests/
71│
72├── shared/                          # Shared kernel (use sparingly)
73│   └── domain_events/
74│       └── base_event.py
75└── docker-compose.yml
76```
77 
78---
79 
80## Onion Architecture vs. Clean Architecture
81 
82Both enforce inward-pointing dependencies. The difference is terminology and layering granularity:
83 
84| Concern | Clean Architecture | Onion Architecture |
85|---|---|---|
86| Innermost ring | Entities | Domain Model |
87| Second ring | Use Cases | Domain Services |
88| Third ring | Interface Adapters | Application Services |
89| Outermost ring | Frameworks & Drivers | Infrastructure / UI / Tests |
90| Key insight | Controller is an adapter | Application Services = Use Cases |
91 
92Onion Architecture makes the Domain Services layer explicit — it hosts pure domain logic that spans multiple entities but has no I/O:
93 
94```python
95# onion/domain/services/pricing_service.py
96from domain.entities.product import Product
97from domain.value_objects.money import Money
98from domain.value_objects.discount import Discount
99 
100class PricingService:
101    """
102    Domain service: logic that doesn't belong to a single entity.
103    No ports or adapters here — purely domain computation.
104    """
105 
106    def apply_bulk_discount(self, product: Product, quantity: int) -> Money:
107        if quantity >= 100:
108            discount = Discount(percentage=20)
109        elif quantity >= 50:
110            discount = Discount(percentage=10)
111        else:
112            discount = Discount(percentage=0)
113        return product.price.apply_discount(discount)
114 
115    def calculate_order_total(self, items: list[tuple[Product, int]]) -> Money:
116        subtotals = [self.apply_bulk_discount(p, q) for p, q in items]
117        return sum(subtotals[1:], subtotals[0]) if subtotals else Money(0, "USD")
118```
119 
120---
121 
122## Anti-Corruption Layer (ACL)
123 
124When the `Ordering` context must fetch product data from the `Catalog` context, it should never use `Catalog`'s domain model directly. An ACL translates between the two models:
125 
126```python
127# ordering/domain/interfaces/catalog_client.py
128from abc import ABC, abstractmethod
129from ordering.domain.value_objects.product_snapshot import ProductSnapshot
130 
131class CatalogClientPort(ABC):
132    """
133    Ordering's view of product data. Uses Ordering's own value object,
134    not Catalog's Product entity.
135    """
136 
137    @abstractmethod
138    async def get_product_snapshot(self, sku: str) -> ProductSnapshot: ...
139 
140 
141# ordering/domain/value_objects/product_snapshot.py
142from dataclasses import dataclass
143from ordering.domain.value_objects.money import Money
144 
145@dataclass(frozen=True)
146class ProductSnapshot:
147    """Ordering's local representation of a product at order time."""
148    sku: str
149    name: str
150    unit_price: Money
151    available: bool
152 
153 
154# ordering/adapters/acl/catalog_http_client.py
155import httpx
156from ordering.domain.interfaces.catalog_client import CatalogClientPort
157from ordering.domain.value_objects.product_snapshot import ProductSnapshot
158from ordering.domain.value_objects.money import Money
159 
160class CatalogHttpClient(CatalogClientPort):
161    """
162    ACL adapter: calls Catalog's HTTP API and translates
163    Catalog's response schema into Ordering's ProductSnapshot.
164    """
165 
166    def __init__(self, base_url: str, http_client: httpx.AsyncClient):
167        self._base_url = base_url
168        self._http = http_client
169 
170    async def get_product_snapshot(self, sku: str) -> ProductSnapshot:
171        response = await self._http.get(f"{self._base_url}/products/{sku}")
172        response.raise_for_status()
173        data = response.json()
174 
175        # Translation: Catalog speaks "price_cents" + "currency_code";
176        # Ordering speaks Money(amount, currency).
177        return ProductSnapshot(
178            sku=data["sku"],
179            name=data["title"],              # field name differs between contexts
180            unit_price=Money(
181                amount=data["price_cents"],
182                currency=data["currency_code"],
183            ),
184            available=data["stock_count"] > 0,
185        )
186 
187 
188# Test ACL with a stub — no HTTP required
189class StubCatalogClient(CatalogClientPort):
190    def __init__(self, products: dict[str, ProductSnapshot]):
191        self._products = products
192 
193    async def get_product_snapshot(self, sku: str) -> ProductSnapshot:
194        if sku not in self._products:
195            raise ValueError(f"Unknown SKU: {sku}")
196        return self._products[sku]
197```
198 
199---
200 
201## Context Map — Relationships Between Bounded Contexts
202 
203```
204┌─────────────────────────────────────────────────────────────────┐
205│                        E-Commerce System                         │
206│                                                                  │
207│   ┌─────────────┐   Open Host   ┌─────────────────────────┐    │
208│   │  Identity   │──────────────▶│        Ordering          │    │
209│   │  Context    │               │  (uses CustomerId VO,    │    │
210│   │             │               │   not User entity)       │    │
211│   └─────────────┘               └─────────────────────────┘    │
212│                                          │ ACL                   │
213│                                          ▼                       │
214│                                 ┌─────────────────┐             │
215│   ┌─────────────┐  Shared       │    Catalog      │             │
216│   │  Payments   │  Kernel       │    Context      │             │
217│   │  Context    │◀─────────────▶│                 │             │
218│   │             │  (Money VO)   └─────────────────┘             │
219│   └─────────────┘                                               │
220└─────────────────────────────────────────────────────────────────┘
221 
222Relationship types:
223  Open Host Service  — upstream provides a stable API for many downstream contexts
224  ACL (Anti-Corruption Layer) — downstream translates upstream model to its own
225  Shared Kernel     — two contexts share a small, explicitly governed sub-model
226  Conformist        — downstream adopts upstream model as-is (last resort)
227```
228 
229---
230 
231## Dependency Injection Wiring — Infrastructure Layer
232 
233All the abstract interfaces are wired to concrete implementations in the infrastructure layer (or a DI container). Nothing else in the codebase knows which concrete class is used:
234 
235```python
236# infrastructure/container.py
237from functools import lru_cache
238import asyncpg
239from adapters.repositories.postgres_user_repository import PostgresUserRepository
240from adapters.gateways.stripe_payment_gateway import StripePaymentAdapter
241from use_cases.create_user import CreateUserUseCase
242from infrastructure.config import Settings
243 
244@lru_cache
245def get_settings() -> Settings:
246    return Settings()
247 
248async def get_db_pool() -> asyncpg.Pool:
249    settings = get_settings()
250    return await asyncpg.create_pool(settings.database_url)
251 
252async def get_create_user_use_case() -> CreateUserUseCase:
253    pool = await get_db_pool()
254    repo = PostgresUserRepository(pool=pool)
255    return CreateUserUseCase(user_repository=repo)
256 
257# In tests, replace get_create_user_use_case with a version
258# that injects InMemoryUserRepository — no other code changes needed.
259```
260 
261---
262 
263## Aggregate Design Heuristics
264 
265Use these rules when deciding aggregate boundaries:
266 
267| Question | Guidance |
268|---|---|
269| Should these two objects always be consistent together? | Put them in the same aggregate. |
270| Can they be eventually consistent? | Put them in separate aggregates; use domain events to sync. |
271| Is one object the "owner" that controls access? | That object is the aggregate root. |
272| Does removing the root make the child meaningless? | Child belongs inside the aggregate. |
273| Are you loading thousands of objects to change one? | Aggregate is too large — split it. |
274 
275**Practical example — Order vs. Customer:**
276 
277```python
278# Bad: Customer aggregate holds full Order objects
279class Customer:
280    def __init__(self):
281        self._orders: list[Order] = []   # loads all orders every time
282 
283# Good: Customer holds Order IDs only; Order is its own aggregate
284class Customer:
285    def __init__(self):
286        self._order_ids: list[str] = []  # lightweight reference
287 
288class Order:
289    def __init__(self, id: str, customer_id: str):
290        self.id = id
291        self.customer_id = customer_id   # reference back, not the full object
292```
293 
294---
295 
296## Domain Events — Publishing and Handling
297 
298Domain events decouple aggregates that need to react to each other's state changes:
299 
300```python
301# domain/events/order_events.py
302from dataclasses import dataclass, field
303from datetime import datetime
304 
305@dataclass
306class DomainEvent:
307    occurred_at: datetime = field(default_factory=datetime.utcnow)
308 
309@dataclass
310class OrderSubmittedEvent(DomainEvent):
311    order_id: str = ""
312    customer_id: str = ""
313    total_cents: int = 0
314    currency: str = "USD"
315 
316 
317# adapters/event_publisher/postgres_outbox.py
318# Transactional outbox pattern: write events to the same DB transaction as state
319import json
320 
321class PostgresOutboxPublisher:
322    """
323    Writes domain events to an outbox table in the same transaction
324    as the aggregate state. A separate relay process reads and publishes
325    to the message broker. Guarantees at-least-once delivery.
326    """
327 
328    async def publish(self, conn, events: list[DomainEvent]):
329        for event in events:
330            await conn.execute(
331                """
332                INSERT INTO outbox (event_type, payload, published_at)
333                VALUES ($1, $2, NULL)
334                """,
335                type(event).__name__,
336                json.dumps(event.__dict__, default=str),
337            )
338 
339 
340# use_cases/place_order.py — aggregate saves, events are extracted and stored
341class PlaceOrderUseCase:
342    def __init__(self, order_repo: OrderRepository, event_publisher: PostgresOutboxPublisher):
343        self.orders = order_repo
344        self.publisher = event_publisher
345 
346    async def execute(self, request: PlaceOrderRequest) -> PlaceOrderResponse:
347        order = Order(id=str(uuid.uuid4()), customer_id=request.customer_id)
348        for item in request.items:
349            order.add_item(product=item.product, quantity=item.quantity)
350        order.submit()
351 
352        async with self.db.transaction() as conn:
353            await self.orders.save(order, conn)
354            await self.publisher.publish(conn, order.pop_events())
355 
356        return PlaceOrderResponse(order_id=order.id, success=True)
357```
358 
359---
360 
361## Detecting and Breaking Dependency Cycles
362 
363Common symptoms and their structural fixes:
364 
365```
366Symptom: use_cases/create_order.py imports from adapters/email_sender.py
367Fix:     Create domain/interfaces/notification_service.py (abstract port).
368         use_cases imports the port. adapters implements it.
369         DI container wires them together.
370 
371Symptom: domain/entities/user.py imports from infrastructure/config.py
372Fix:     Pass config values as constructor arguments or environment at
373         the infrastructure boundary. Domain entities must not read config.
374 
375Symptom: Two aggregates import each other
376Fix:     Introduce a domain event. Aggregate A emits OrderPlaced.
377         Aggregate B's use case subscribes and reacts. They never import
378         each other.
379 
380Symptom: Repository imports a use case to "do extra work" after saving
381Fix:     Extract the extra work into a separate domain service or use case.
382         Repositories persist state only; they do not orchestrate behaviour.
383```
384 
385Visual dependency check — run this and look for any arrow pointing outward:
386 
387```bash
388# Install: pip install pydeps
389pydeps app --max-bacon=4 --cluster --rankdir=BT
390# Expected: domain has no outgoing edges to adapters or infrastructure
391```
392