@martinffx/atelier 1.2.1 → 1.3.0

package/skills/oracle-architect/references/data-modeling.md

@@ -1,318 +0,0 @@
-# Data Modeling Reference
-
-Entity design principles, schema patterns, and access pattern optimization.
-
-## Entity Design
-
-### Design Process
-1. Start with domain concepts from product requirements
-2. Identify aggregates and their boundaries
-3. Define attributes and relationships
-4. Add validation rules and invariants
-5. Include transformation methods (fromRequest, toRecord, toResponse)
-
-### Entity Structure
-
-**Core transformation methods:**
-```typescript
-class Order {
-  // Create from external request
-  static fromRequest(req: CreateOrderRequest): Order
-
-  // Create from database record
-  static fromRecord(record: OrderRecord): Order
-
-  // Convert to database record
-  toRecord(): OrderRecord
-
-  // Convert to API response
-  toResponse(): OrderResponse
-
-  // Validate invariants
-  validate(): Result<Order>
-}
-```
-
-### Example Entity Design
-
-```typescript
-class Order {
-  constructor(
-    public readonly id: string,
-    public readonly customerId: string,
-    public readonly items: OrderItem[],
-    public readonly status: OrderStatus,
-    public readonly total: number,
-    public readonly createdAt: Date,
-    public readonly metadata: OrderMetadata
-  ) {}
-
-  static fromRequest(req: CreateOrderRequest): Order {
-    return new Order(
-      generateId(),
-      req.customerId,
-      req.items.map(i => new OrderItem(i)),
-      'pending',
-      req.items.reduce((sum, i) => sum + i.price * i.quantity, 0),
-      new Date(),
-      { source: req.source || 'web' }
-    );
-  }
-
-  toRecord(): OrderRecord {
-    return {
-      id: this.id,
-      customer_id: this.customerId,
-      items: JSON.stringify(this.items),
-      status: this.status,
-      total: this.total,
-      created_at: this.createdAt.toISOString(),
-      metadata: this.metadata
-    };
-  }
-
-  toResponse(): OrderResponse {
-    return {
-      id: this.id,
-      customerId: this.customerId,
-      items: this.items,
-      status: this.status,
-      total: this.total,
-      createdAt: this.createdAt.toISOString()
-    };
-  }
-
-  validate(): Result<Order> {
-    if (this.items.length === 0) {
-      return Err('Order must have at least one item');
-    }
-    if (this.total < 0) {
-      return Err('Order total cannot be negative');
-    }
-    return Ok(this);
-  }
-}
-```
-
-## Schema Patterns
-
-### Relational Design
-
-**Orders table:**
-```sql
-CREATE TABLE orders (
-  id UUID PRIMARY KEY,
-  customer_id UUID NOT NULL REFERENCES customers(id),
-  status VARCHAR(20) NOT NULL CHECK (status IN ('pending', 'confirmed', 'shipped', 'delivered')),
-  total DECIMAL(10,2) NOT NULL,
-  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_orders_customer ON orders(customer_id);
-CREATE INDEX idx_orders_status ON orders(status);
-CREATE INDEX idx_orders_created ON orders(created_at DESC);
-```
-
-**Order items (normalized):**
-```sql
-CREATE TABLE order_items (
-  id UUID PRIMARY KEY,
-  order_id UUID NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
-  product_id UUID NOT NULL,
-  quantity INT NOT NULL CHECK (quantity > 0),
-  price DECIMAL(10,2) NOT NULL,
-  UNIQUE(order_id, product_id)
-);
-
-CREATE INDEX idx_order_items_order ON order_items(order_id);
-```
-
-### DynamoDB Single Table Design
-
-**Items structure:**
-```typescript
-{
-  PK: 'ORDER#123',
-  SK: 'ORDER#123',
-  type: 'Order',
-  customerId: 'CUST#456',
-  status: 'pending',
-  total: 99.99,
-  items: [...],
-  createdAt: '2024-01-21T10:00:00Z',
-
-  // GSI for customer lookup
-  GSI1PK: 'CUST#456',
-  GSI1SK: 'ORDER#2024-01-21T10:00:00Z',
-
-  // GSI for status lookup
-  GSI2PK: 'pending',
-  GSI2SK: 'ORDER#2024-01-21T10:00:00Z'
-}
-
-{
-  PK: 'ORDER#123',
-  SK: 'ITEM#item-001',
-  type: 'OrderItem',
-  productId: 'PROD#999',
-  quantity: 2,
-  price: 49.99
-}
-```
-
-**Key design:**
-- PK = partition key (primary lookup)
-- SK = sort key (range queries)
-- GSI = global secondary index (alternative queries)
-
-## Access Patterns
-
-### Define Patterns First
-
-List all data access patterns **before** designing schema:
-
-1. **Find order by ID**
-   - Query: `PK = ORDER#123, SK = ORDER#123`
-   - Index: Primary key
-
-2. **List orders by customer**
-   - Query: `GSI1PK = CUST#456`
-   - Index: Global secondary index
-
-3. **List pending orders by date**
-   - Query: `GSI2PK = pending, GSI2SK > date`
-   - Index: Global secondary index sorted by date
-
-4. **Count orders by status**
-   - Query: Scan with filter (or GSI)
-   - Performance: Consider status table
-
-5. **Get recent orders for customer**
-   - Query: `GSI1PK = CUST#456` sorted by date DESC
-   - Index: Global secondary index
-
-### Query Optimization
-
-**N+1 Problem:**
-```typescript
-// BAD: N+1 queries
-const orders = await orderRepo.findByCustomer(customerId);
-const itemsPerOrder = await Promise.all(
-  orders.map(o => itemRepo.findByOrder(o.id))  // N queries
-);
-
-// GOOD: Single query with denormalization
-const orderData = await db.orders
-  .where({ customerId })
-  .select(['*', 'items']) // Includes denormalized items
-  .sort({ createdAt: 'DESC' });
-```
-
-**Index Coverage:**
-```sql
--- Bad: Full table scan
-SELECT * FROM orders WHERE customer_id = $1;
-
--- Good: Index-covered query
-CREATE INDEX idx_orders_customer_status
-ON orders(customer_id, status);
-
-SELECT * FROM orders
-WHERE customer_id = $1 AND status = 'pending';
-```
-
-## Data Transformation Patterns
-
-### Request → Entity → Record → Response Flow
-
-```typescript
-// 1. HTTP Request arrives
-POST /orders
-{
-  "customerId": "cust-123",
-  "items": [{ "productId": "prod-1", "quantity": 2 }]
-}
-
-// 2. Router parses to request type
-const request: CreateOrderRequest = req.body;
-
-// 3. Entity transforms from request (with ID generation)
-const order = Order.fromRequest(request);
-
-// 4. Entity validates business rules
-const validation = order.validate();
-if (!validation.ok) return error;
-
-// 5. Service performs logic, uses repository
-await repo.save(order.toRecord());
-
-// 6. Repository converts to database record
-{
-  id: "order-abc",
-  customer_id: "cust-123",
-  items: "[...]",
-  status: "pending",
-  created_at: "2024-01-21T10:00:00Z"
-}
-
-// 7. Response converts from record
-const response = order.toResponse();
-
-// 8. HTTP Response sends
-{
-  "id": "order-abc",
-  "customerId": "cust-123",
-  "items": [...],
-  "status": "pending"
-}
-```
-
-### Transformation Considerations
-
-**Immutability:**
-```typescript
-// Bad: Mutation during transform
-toRecord(): OrderRecord {
-  this.items.forEach(i => i.status = 'recorded');
-  return { items: this.items };
-}
-
-// Good: No side effects
-toRecord(): OrderRecord {
-  return {
-    items: this.items.map(i => ({
-      ...i,
-      // Transform properties as needed
-    }))
-  };
-}
-```
-
-**Versioning:**
-```typescript
-// Handle multiple API versions
-toResponse(version: 'v1' | 'v2'): OrderResponse {
-  const base = {
-    id: this.id,
-    customerId: this.customerId,
-    status: this.status
-  };
-
-  if (version === 'v2') {
-    return { ...base, total: this.total };
-  }
-  return base;
-}
-```
-
-**Partial Loading:**
-```typescript
-// Only load fields needed for the operation
-async findOrderSummary(id: string): Promise<OrderSummary> {
-  const record = await db.orders
-    .select(['id', 'status', 'total'])
-    .findOne({ id });
-  return { id: record.id, status: record.status, total: record.total };
-}
-```

package/skills/oracle-architect/references/ddd-patterns.md

@@ -1,348 +0,0 @@
-# DDD Patterns Reference
-
-Domain-Driven Design patterns for modeling business domains and enforcing consistency.
-
-## Aggregates
-
-**Definition:** Cluster of domain objects treated as a single unit for data changes
-
-**Rules:**
-- One entity is the aggregate root (e.g., Order)
-- External references only to the root
-- Changes go through the root
-- Root enforces invariants
-
-**Example:**
-```typescript
-class Order {  // Aggregate root
-  private items: OrderItem[];  // Part of aggregate
-
-  addItem(item: OrderItem): Result<Order> {
-    // Root enforces invariants
-    if (this.items.length >= 100) {
-      return Err('Order cannot have more than 100 items');
-    }
-    this.items.push(item);
-    return Ok(this);
-  }
-}
-```
-
-**Business Rules Enforcement:**
-```typescript
-class Order {
-  private status: OrderStatus;
-  private appliedDiscounts: Discount[] = [];
-
-  applyDiscount(discount: Discount): Result<void> {
-    // Business rule: can't apply discount to shipped orders
-    if (this.status === 'shipped') {
-      return Err('Cannot discount shipped orders');
-    }
-
-    // Business rule: no duplicate discounts
-    if (this.appliedDiscounts.some(d => d.id === discount.id)) {
-      return Err('Discount already applied');
-    }
-
-    this.appliedDiscounts.push(discount);
-    return Ok(undefined);
-  }
-}
-```
-
-## Value Objects
-
-**Definition:** Immutable objects defined by their attributes, not identity
-
-**Characteristics:**
-- No identity (equality by value)
-- Immutable
-- Self-validating
-- Encapsulate validation logic
-
-**Example:**
-```typescript
-class Money {
-  constructor(
-    public readonly amount: number,
-    public readonly currency: string
-  ) {
-    if (amount < 0) throw new Error('Amount cannot be negative');
-    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
-      throw new Error('Unsupported currency');
-    }
-  }
-
-  add(other: Money): Money {
-    if (this.currency !== other.currency) {
-      throw new Error('Cannot add different currencies');
-    }
-    return new Money(this.amount + other.amount, this.currency);
-  }
-
-  equals(other: Money): boolean {
-    return this.amount === other.amount && this.currency === other.currency;
-  }
-
-  static fromCents(cents: number, currency: string): Money {
-    return new Money(cents / 100, currency);
-  }
-}
-```
-
-**More Examples:**
-```typescript
-// Email VO with validation
-class Email {
-  readonly value: string;
-
-  constructor(value: string) {
-    if (!this.isValid(value)) throw new Error('Invalid email');
-    this.value = value.toLowerCase();
-  }
-
-  private isValid(email: string): boolean {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-  }
-
-  equals(other: Email): boolean {
-    return this.value === other.value;
-  }
-}
-
-// Address VO with composition
-class Address {
-  constructor(
-    public readonly street: string,
-    public readonly city: string,
-    public readonly zipCode: string,
-    public readonly country: string
-  ) {}
-
-  equals(other: Address): boolean {
-    return this.street === other.street &&
-           this.city === other.city &&
-           this.zipCode === other.zipCode &&
-           this.country === other.country;
-  }
-}
-```
-
-## Domain Events
-
-**Definition:** Something that happened in the domain that domain experts care about
-
-**Characteristics:**
-- Immutable facts about what happened
-- Named in past tense
-- Include context about what changed
-- Timestamped
-
-**Example:**
-```typescript
-class OrderPlaced {
-  constructor(
-    public readonly orderId: string,
-    public readonly customerId: string,
-    public readonly total: number,
-    public readonly occurredAt: Date
-  ) {}
-}
-
-// Service publishes events
-const order = await orderService.createOrder(request);
-await eventBus.publish(
-  new OrderPlaced(order.id, order.customerId, order.total, new Date())
-);
-
-// Events cross bounded contexts
-class OrderShipped {
-  constructor(
-    public readonly orderId: string,
-    public readonly shippingAddress: Address,
-    public readonly trackingNumber: string,
-    public readonly occurredAt: Date
-  ) {}
-}
-```
-
-**Event-Driven Workflows:**
-```typescript
-// Order context publishes OrderPlaced
-// Inventory context listens and consumes
-class InventoryService {
-  async handleOrderPlaced(event: OrderPlaced): Promise<Result<void>> {
-    // Reserve inventory in response to order
-    const result = await this.inventoryRepo.reserve(event.orderId);
-    if (!result.ok) {
-      // Handle reservation failure
-      await this.eventBus.publish(new InventoryReservationFailed(event.orderId));
-    }
-    return result;
-  }
-}
-```
-
-## Bounded Contexts
-
-**Definition:** Explicit boundaries where a domain model applies
-
-**Guidelines:**
-- Each context has its own ubiquitous language
-- Contexts communicate via well-defined contracts
-- Same concept may have different models in different contexts
-- Example: "Customer" in Sales context vs "User" in Auth context
-
-**Context Composition:**
-```
-Bounded Context: "Orders"
-┌────────────────────────────────────────────────────────────────┐
-│                                                                │
-│   Effectful Edge                    Functional Core            │
-│   ┌──────────────────┐             ┌──────────────────┐       │
-│   │ Router           │────────────▶│ Service          │       │
-│   │ POST /orders     │             │ OrderService     │       │
-│   └──────────────────┘             └────────┬─────────┘       │
-│                                              │                 │
-│   ┌──────────────────┐             ┌────────▼─────────┐       │
-│   │ Repository       │◀────────────│ Aggregate        │       │
-│   │ OrderRepository  │             │ Order (root)     │       │
-│   └──────────────────┘             │ └─ OrderItem[]   │       │
-│                                    │ └─ Money (VO)    │       │
-│   ┌──────────────────┐             └──────────────────┘       │
-│   │ Producer         │◀── Domain Event: OrderPlaced           │
-│   └────────┬─────────┘                                        │
-└────────────│───────────────────────────────────────────────────┘
-             │
-             ▼ Events cross context boundaries
-┌────────────────────────────────────────────────────────────────┐
-│ Bounded Context: "Inventory"                                   │
-│   Consumer ──▶ InventoryService ──▶ StockLevel (Aggregate)     │
-└────────────────────────────────────────────────────────────────┘
-```
-
-**Context Anti-Patterns:**
-- Shared database (breaks boundary enforcement)
-- Generic "core" or "common" domain (pollutes context boundaries)
-- Cross-context validation (move validation to appropriate context)
-- Tight coupling via shared types (use context-specific DTOs)
-
-## Composition Rules
-
-| DDD Pattern | Maps To | Location |
-|-------------|---------|----------|
-| Bounded Context | Module/Package boundary | Contains all layers |
-| Aggregate | Entity cluster | Functional Core |
-| Aggregate Root | Primary Entity | Entity layer |
-| Value Object | Immutable type | Entity layer |
-| Domain Event | Event class | Published from Service, consumed by edge |
-| Repository | Data access | Effectful Edge (interface in Core) |
-
-**Key Interactions:**
-1. **Router → Service**: HTTP request parsed, passed to service
-2. **Service → Aggregate**: Service orchestrates aggregate operations
-3. **Aggregate → Repository**: Service uses repository to persist aggregate
-4. **Service → Producer**: Service publishes domain events after state change
-5. **Consumer → Service**: Events from other contexts trigger service operations
-
-## Seam Placement
-
-Where you put the seam matters as much as what goes behind it.
-
-### Core/Edge Seam
-
-The primary seam runs between the functional core and the effectful edge:
-
-```
-┌─────────────────────────────────┐
-│  Functional Core (pure)         │
-│  ┌──────────────────────────┐   │
-│  │ OrderService             │   │
-│  │   createOrder() ────────┼───┼──▶ (seam)
-│  │   processPayment()       │   │
-│  └──────────────────────────┘   │
-└─────────────────────────────────┘
-              │
-              ▼ seam
-┌─────────────────────────────────┐
-│  Effectful Edge (IO)            │
-│  ┌──────────────────────────┐   │
-│  │ PostgresOrderRepository  │◀──┼── adapter
-│  │ HttpPaymentClient        │   │   adapter
-│  │ InMemoryOrderRepository  │   │   adapter (test)
-│  └──────────────────────────┘   │
-└─────────────────────────────────┘
-```
-
-**Rules:**
-- Core defines the interface; edge implements it (dependency inversion)
-- The seam must have **at least two adapters** to be real (production + test)
-- Core never imports edge code; edge imports core interfaces
-
-### Internal Seams
-
-A deep module can have **internal seams** — private to its implementation, used by its own tests:
-
-```typescript
-class Order {
-  // External seam (public interface)
-  validate(): Result<Order> { ... }
-
-  // Internal seam (private, tested directly)
-  private calculateTax(subtotal: number): Money { ... }
-}
-```
-
-Internal seams let you test complex logic without exposing it in the public interface.
-
-### When to Create a Seam
-
-Use the **adapter rule**: one adapter = hypothetical; two = real.
-
-| Scenario | Action |
-|----------|--------|
-| One database implementation, no test fake | No seam needed. Direct dependency is simpler. |
-| One database implementation, test fake exists | Extract interface. The fake is the second adapter. |
-| Multiple database implementations (Postgres + DynamoDB) | Extract interface. The implementations are the adapters. |
-| External API with one client | Direct dependency. Introduce seam only when you need a mock/stub for testing. |
-
-### Anti-Patterns
-
-**Seam at every dependency:**
-```typescript
-// ❌ Too many seams — every dependency gets an interface
-interface IValidator { ... }
-interface IFormatter { ... }
-interface IConverter { ... }
-// Each has one adapter. Indirection without value.
-```
-
-**No seam at the core/edge boundary:**
-```typescript
-// ❌ Core imports edge directly
-import { db } from '../edge/postgres';
-class OrderService {
-  async createOrder(req) {
-    await db.orders.create(...); // Core knows about Postgres
-  }
-}
-```
-
-**Leaky seam:**
-```typescript
-// ❌ Interface exposes implementation details
-interface OrderRepository {
-  queryRaw(sql: string): Promise<Row[]>; // Caller knows SQL
-  beginTransaction(): Promise<Transaction>; // Caller manages transactions
-}
-// The seam leaks. Callers become coupled to the database.
-```
-
-### Seam Placement Checklist
-
-Before introducing a new seam, verify:
-- [ ] At least two adapters will exist (production + test, or multiple production)
-- [ ] The interface hides implementation details (no SQL, no HTTP, no framework types)
-- [ ] The core doesn't import edge code
-- [ ] Deleting the module would re-appear complexity across N callers