Add Event Sourcing & Transactional Outbox guidance; expand anti-patterns and migration playbook

CONTENT-GAP-AUDIT.md

@@ -0,0 +1,17 @@
+# Content Gap Audit (Design-Patterns Repo)
+
+## Critical
+- Added missing **Transactional Outbox** system pattern and **Dual Writes** anti-pattern coverage.
+- Added migration path **Direct Publish -> Transactional Outbox** to reduce data/event inconsistency risk.
+
+## High
+- Added **Event Sourcing** as a common system pattern not previously covered.
+- Added **N+1 Query Problem** anti-pattern because it is a high-frequency production issue.
+
+## Medium
+- Added **Version Baseline** section in framework catalog to make version intent explicit and reviewable.
+- Verified all references listed in `skills/design-patterns/SKILL.md` exist in repository.
+
+## Low
+- Ran a markdown link/path scan (no actionable broken local links detected).
+- Minor wording cleanup happened indirectly via added sections.

README.md

@@ -119,8 +119,8 @@ Step 4: Thin routes.ts to HTTP-only controller
 | Capability | Reference |
 |------------|----------|
 | 🧪 **Testing Patterns** — How to test every pattern | `references/testing-patterns.md` |
-| 🚫 **Anti-Patterns Catalog** — 15 code smells with detection & cures | `references/anti-patterns.md` |
-| 🔄 **Migration Playbook** — 5 step-by-step refactoring guides | `references/migration-playbook.md` |
+| 🚫 **Anti-Patterns Catalog** — 17 code smells with detection & cures | `references/anti-patterns.md` |
+| 🔄 **Migration Playbook** — 6 step-by-step refactoring guides | `references/migration-playbook.md` |
 | 📄 **Output Formats** — ADR, Health Check, Comparison Matrix | `references/output-format.md` |
 
 ### Framework-Specific Implementations
@@ -180,8 +180,8 @@ skills/design-patterns/
     ├── system-patterns.md        # Microservices, Event-Driven, Cloud
     ├── framework-catalog.md      # Next.js, FastAPI, NestJS, Django, Express, Go
     ├── testing-patterns.md       # ✨ NEW — Unit/Integration/E2E test code
-    ├── anti-patterns.md          # ✨ NEW — 15 anti-patterns with detection
-    ├── migration-playbook.md     # ✨ NEW — 5 migration guides
+    ├── anti-patterns.md          # ✨ NEW — 17 anti-patterns with detection
+    ├── migration-playbook.md     # ✨ NEW — 6 migration guides
     └── output-format.md          # ✨ NEW — ADR, Reports, Health Check
 
 RELEASE-NOTES.md

skills/design-patterns/SKILL.md

@@ -244,6 +244,6 @@ Every design-patterns analysis MUST follow:
 - `references/system-patterns.md` — Microservices, Event-Driven, Circuit Breaker, Saga, Cloud patterns
 - `references/framework-catalog.md` — Pattern implementations for Next.js, FastAPI, NestJS, Django, Express, Go
 - `references/testing-patterns.md` — How to test every pattern (unit, integration, e2e) with real test code
-- `references/anti-patterns.md` — 15 anti-patterns catalog with detection commands, severities, and cures
-- `references/migration-playbook.md` — 5 step-by-step migration guides with verification checkpoints
+- `references/anti-patterns.md` — 17 anti-patterns catalog with detection commands, severities, and cures
+- `references/migration-playbook.md` — 6 step-by-step migration guides with verification checkpoints
 - `references/output-format.md` — ADR template, Refactoring Report, Health Check, Pattern Comparison

skills/design-patterns/references/anti-patterns.md

@@ -341,11 +341,31 @@ class Order {
 
 **Cure:** Start with Module Boundaries → Service Layer → Eventually Clean Architecture
 
+
+---
+
+### 13. N+1 Query Problem
+
+**Severity:** 🔴 High
+
+**Detection:** Repeated query pattern inside loops or ORM lazy-loading waterfalls.
+
+```typescript
+// 🔴 N+1: one query for orders + one query per order for items
+const orders = await prisma.order.findMany();
+for (const order of orders) {
+  order.items = await prisma.orderItem.findMany({ where: { orderId: order.id } });
+}
+```
+
+**Cure:** Eager loading (`include`/`select`), batching, and query-level aggregation.
+
+
 ---
 
 ## System-Level Anti-Patterns
 
-### 13. Distributed Monolith
+### 14. Distributed Monolith
 
 **Severity:** 🚨 Critical
 
@@ -361,7 +381,7 @@ class Order {
 
 ---
 
-### 14. Chatty Services
+### 15. Chatty Services
 
 **Severity:** 🔴 High
 
@@ -371,7 +391,7 @@ class Order {
 
 ---
 
-### 15. No Timeout / No Retry
+### 16. No Timeout / No Retry
 
 **Severity:** 🔴 High
 
@@ -421,3 +441,17 @@ Run this checklist on any module before refactoring:
 - [ ] Shared database between services?
 - [ ] Services that must deploy together?
 ```
+
+
+### 17. Dual Writes (DB + Event Bus without Outbox)
+
+**Severity:** 🚨 Critical
+
+**Detection:** Application writes DB and publishes message in separate non-atomic steps.
+
+**Symptoms:**
+- Order exists in DB but `order.created` event missing
+- Event published but DB transaction rolled back
+- Hard-to-reconcile states across services
+
+**Cure:** Transactional Outbox pattern with idempotent consumers.

skills/design-patterns/references/architecture-patterns.md

@@ -99,15 +99,20 @@ export class UserRepository {
 ```python
 # routers/user.py — Controller
 from fastapi import APIRouter, Depends
+from schemas.user import CreateUserDTO, User
 from services.user_service import UserService
 
 router = APIRouter()
 
-@router.post("/users", status_code=201)
+@router.post("/users", status_code=201, response_model=User)
 async def create_user(data: CreateUserDTO, service: UserService = Depends()):
     return await service.create(data)
 
 # services/user_service.py — Business Logic
+from fastapi import Depends, HTTPException
+from repositories.user_repository import UserRepository
+from utils.security import hash_password
+
 class UserService:
     def __init__(self, repo: UserRepository = Depends()):
         self.repo = repo
@@ -117,12 +122,17 @@ class UserService:
         if existing:
             raise HTTPException(409, "Email already exists")
         hashed = hash_password(data.password)
-        return await self.repo.save({**data.dict(), "password": hashed})
+        return await self.repo.save({**data.model_dump(), "password": hashed})
 
 # repositories/user_repository.py — Data Access
+from db.client import database
+
 class UserRepository:
     async def find_by_email(self, email: str) -> User | None:
         return await database.users.find_one({"email": email})
+
+    async def save(self, data: dict) -> User:
+        return await database.users.insert_one(data)
 ```
 
 ---

skills/design-patterns/references/code-patterns.md

@@ -205,6 +205,7 @@ if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;
 **Python Example:**
 ```python
 # config.py — Thread-safe Singleton
+import os
 import threading
 
 class AppConfig:

skills/design-patterns/references/framework-catalog.md

@@ -5,6 +5,22 @@
 
 ---
 
+
+## Version Baseline (Validate Quarterly)
+
+> Keep examples aligned with actively maintained major versions.
+
+| Framework | Baseline in this catalog |
+|-----------|--------------------------|
+| Next.js | 15.x (App Router + Server Actions) |
+| FastAPI | 0.110+ (Pydantic v2 style) |
+| NestJS | 10.x+ |
+| Django | 5.x |
+| Express | 5.x |
+| Go | 1.22+ |
+
+---
+
 ## Next.js (App Router)
 
 ### Recommended Architecture

skills/design-patterns/references/migration-playbook.md

@@ -351,6 +351,69 @@ Week 4: Remove old code from monolith
 
 **Step 6: Repeat** for next least-coupled module.
 
+
+---
+
+## Migration 6: Direct Publish → Transactional Outbox
+
+**Difficulty:** ⭐⭐⭐⭐ (Advanced)
+**Time:** 2-5 days
+**Risk:** High (touches write path + async workers)
+
+### Problem Signature
+```typescript
+await orderRepo.save(order);               // DB write
+await eventBus.publish(new OrderCreated);  // separate write (can fail)
+```
+
+### Steps
+
+**Step 1: Add outbox table**
+```sql
+CREATE TABLE outbox_events (
+  id UUID PRIMARY KEY,
+  aggregate_type TEXT NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  sent_at TIMESTAMPTZ
+);
+```
+
+**Step 2: Write business row + outbox row in one transaction**
+```typescript
+await prisma.$transaction(async (tx) => {
+  await tx.order.create({ data: orderData });
+  await tx.outboxEvent.create({
+    data: {
+      aggregateType: 'order',
+      aggregateId: orderData.id,
+      eventType: 'order.created',
+      payload: orderData,
+    },
+  });
+});
+```
+
+**Step 3: Add outbox publisher worker**
+- Poll pending rows in small batches
+- Publish to broker
+- Mark rows as sent
+- Retry with exponential backoff
+
+**Step 4: Make consumers idempotent**
+- Deduplicate by event ID
+- Store processed event IDs
+
+**Step 5: Verify**
+```bash
+# Simulate broker outage, ensure events remain in outbox pending state
+npm test
+```
+
+
 ---
 
 ## Migration Verification Checklist

skills/design-patterns/references/system-patterns.md

@@ -282,6 +282,50 @@ Phase 3: /api/users + /api/orders → New
 Phase N: 100% traffic → New, Legacy decommissioned
 ```
 
+
+---
+
+## 9. Event Sourcing Pattern
+
+### Problem
+Auditability and temporal debugging are hard when you only store the latest row state.
+
+### Solution
+Persist immutable domain events as the source of truth, and rebuild state from the event stream.
+
+### When to Use
+- Need full audit history (fintech, compliance-heavy domains)
+- Need time-travel debugging ("what did we know at T1?")
+- Complex domain workflows where replay is valuable
+
+### Trade-offs
+- Higher implementation complexity than CRUD
+- Requires event versioning strategy
+- Read models usually need separate projections
+
+---
+
+## 10. Transactional Outbox Pattern
+
+### Problem
+Dual-write risk: write DB row succeeds, publish event fails (or vice versa) causing inconsistency.
+
+### Solution
+Write business data and outbox record in ONE local transaction, then publish asynchronously from the outbox.
+
+### Minimal Flow
+```
+1) Begin transaction
+2) Write business entity (e.g., order)
+3) Write outbox event row (e.g., order.created)
+4) Commit
+5) Outbox worker publishes event and marks row as sent
+```
+
+### Why It Matters
+Outbox is the default reliability companion for Event-Driven + Saga systems.
+
+
 ---
 
 ## Pattern Decision Matrix
@@ -295,3 +339,5 @@ Phase N: 100% traffic → New, Legacy decommissioned
 | Legacy migration | Strangler Fig | Medium | Any |
 | Cross-cutting concerns | Sidecar | Medium | 3+ |
 | Monolith too big | Microservices | Very High | 8+ |
+| Need full audit trail + replay | Event Sourcing | High | 5+ |
+| Reliable DB + event publication | Transactional Outbox | Medium | 3+ |

skills/design-patterns/references/testing-patterns.md

@@ -100,6 +100,7 @@ describe("EventBus", () => {
 describe("CommandHistory", () => {
   let history: CommandHistory;
   let cart: Cart;
+  const laptop: CartItem = { id: "1", name: "Laptop", qty: 1 };
 
   beforeEach(() => {
     history = new CommandHistory();
@@ -192,9 +193,11 @@ describe("Middleware Decorators", () => {
 **The Key:** Mock the Repository, test the Service logic.
 
 ```typescript
+import type { Mocked } from "vitest";
+
 describe("UserService", () => {
   let service: UserService;
-  let mockRepo: jest.Mocked<UserRepository>;
+  let mockRepo: Mocked<UserRepository>;
 
   beforeEach(() => {
     mockRepo = {
@@ -232,6 +235,7 @@ describe("UserRepository (Integration)", () => {
   beforeAll(async () => {
     // Use test database
     await prisma.$connect();
+    repo = new UserRepository(prisma);
   });
 
   afterEach(async () => {
@@ -256,15 +260,27 @@ describe("UserRepository (Integration)", () => {
 ```typescript
 // Command side — test business rules
 describe("CreateOrderHandler", () => {
+  let handler: CreateOrderHandler;
+  const mockRepo = { save: vi.fn() };
+  const mockEventBus = { publish: vi.fn() };
+
+  beforeEach(() => {
+    handler = new CreateOrderHandler(mockRepo, mockEventBus);
+  });
+
   it("validates stock before creating order", async () => {
-    const handler = new CreateOrderHandler(mockRepo, mockEventBus);
     await expect(handler.execute(new CreateOrderCommand("user-1", [
       { productId: "p-1", quantity: 999 }, // Exceeds stock
     ]))).rejects.toThrow("Insufficient stock");
   });
 
   it("publishes OrderCreated event", async () => {
+    const validCommand = new CreateOrderCommand("user-1", [
+      { productId: "p-1", quantity: 1 },
+    ]);
+
     await handler.execute(validCommand);
+
     expect(mockEventBus.publish).toHaveBeenCalledWith(
       expect.objectContaining({ type: "OrderCreated" })
     );
@@ -273,6 +289,13 @@ describe("CreateOrderHandler", () => {
 
 // Query side — test data retrieval
 describe("GetOrderSummaryHandler", () => {
+  let handler: GetOrderSummaryHandler;
+  const readDb = { query: vi.fn() };
+
+  beforeEach(() => {
+    handler = new GetOrderSummaryHandler(readDb);
+  });
+
   it("returns denormalized view", async () => {
     const result = await handler.execute(new GetOrderSummaryQuery("ord-1"));
     expect(result).toMatchObject({