@martinffx/atelier 1.2.2 → 1.3.0

package/skills/oracle-architect/references/api-design.md

@@ -1,345 +0,0 @@
-# API Design Reference
-
-REST conventions, request/response contracts, and error handling patterns.
-
-## REST Conventions
-
-### Resource-Oriented Endpoints
-
-**Standard CRUD operations:**
-```
-GET    /orders          # List orders
-POST   /orders          # Create order
-GET    /orders/:id      # Get single order
-PATCH  /orders/:id      # Update order
-DELETE /orders/:id      # Delete order
-```
-
-**Nested resources:**
-```
-GET    /orders/:orderId/items          # List order items
-POST   /orders/:orderId/items          # Add item to order
-GET    /orders/:orderId/items/:itemId  # Get order item
-PATCH  /orders/:orderId/items/:itemId  # Update order item
-DELETE /orders/:orderId/items/:itemId  # Delete order item
-```
-
-### Actions (Non-CRUD Operations)
-
-**Use POST for state transitions:**
-```
-POST /orders/:id/cancel   # Cancel order
-POST /orders/:id/ship     # Ship order
-POST /orders/:id/confirm  # Confirm order
-```
-
-**Reasoning:** These modify state but aren't CRUD operations. They represent domain actions.
-
-**Avoid:**
-```
-PATCH /orders/:id { "action": "cancel" }  # Unclear what changed
-GET   /orders/:id/cancel                  # GET shouldn't have side effects
-```
-
-## Request/Response Contracts
-
-### Request Types
-
-**Create request (POST /resource):**
-```typescript
-interface CreateOrderRequest {
-  customerId: string;
-  items: Array<{
-    productId: string;
-    quantity: number;
-  }>;
-  shippingAddress?: {
-    street: string;
-    city: string;
-    zipCode: string;
-  };
-}
-```
-
-**Update request (PATCH /resource/:id):**
-```typescript
-interface UpdateOrderRequest {
-  status?: 'pending' | 'confirmed' | 'shipped';
-  shippingAddress?: Address;
-  // Only fields that can be updated
-}
-```
-
-**Query parameters:**
-```
-GET /orders?customerId=cust-123&status=pending&limit=20&offset=0
-
-interface ListOrdersQuery {
-  customerId?: string;
-  status?: OrderStatus;
-  limit?: number;  // Default 20, max 100
-  offset?: number; // Pagination offset
-}
-```
-
-### Response Types
-
-**Single resource (GET /resource/:id):**
-```typescript
-interface OrderResponse {
-  id: string;
-  customerId: string;
-  items: OrderItem[];
-  status: 'pending' | 'confirmed' | 'shipped' | 'delivered';
-  total: number;
-  createdAt: string;  // ISO 8601
-  updatedAt: string;
-}
-```
-
-**List response (GET /resource):**
-```typescript
-interface ListOrdersResponse {
-  data: OrderResponse[];
-  pagination: {
-    total: number;
-    limit: number;
-    offset: number;
-    hasMore: boolean;
-  };
-}
-```
-
-**Create response (POST /resource):**
-```typescript
-// Return created resource with 201 status
-interface CreateOrderResponse extends OrderResponse {
-  id: string; // Generated by server
-}
-```
-
-### Timestamp Conventions
-
-**Use ISO 8601 for all timestamps:**
-```json
-{
-  "createdAt": "2024-01-21T10:30:45Z",
-  "updatedAt": "2024-01-21T10:30:45Z",
-  "deletedAt": null
-}
-```
-
-**Never:** Unix timestamps, custom formats, or timezone abbreviations
-
-## Error Handling
-
-### HTTP Status Codes
-
-**Success:**
-- `200 OK` - GET, PATCH succeeded
-- `201 Created` - POST created resource
-- `204 No Content` - DELETE or update with no response body
-
-**Client Errors:**
-- `400 Bad Request` - Invalid input validation
-- `401 Unauthorized` - Missing authentication
-- `403 Forbidden` - Authenticated but insufficient permissions
-- `404 Not Found` - Resource not found
-- `409 Conflict` - State violation (can't transition state)
-- `422 Unprocessable Entity` - Validation failed
-
-**Server Errors:**
-- `500 Internal Server Error` - Unhandled exception
-- `503 Service Unavailable` - Temporary outage
-
-### Error Response Format
-
-**Validation error (400):**
-```typescript
-interface ValidationErrorResponse {
-  error: 'Validation failed';
-  code: 'VALIDATION_ERROR';
-  details: {
-    field: string;
-    message: string;
-  }[];
-}
-
-// Example
-{
-  "error": "Validation failed",
-  "code": "VALIDATION_ERROR",
-  "details": [
-    { "field": "items", "message": "Must have at least one item" },
-    { "field": "customerId", "message": "Invalid customer ID format" }
-  ]
-}
-```
-
-**Business rule violation (409):**
-```typescript
-interface ConflictErrorResponse {
-  error: string;
-  code: string;
-  details?: Record<string, unknown>;
-}
-
-// Example
-{
-  "error": "Cannot cancel shipped order",
-  "code": "ORDER_ALREADY_SHIPPED",
-  "details": {
-    "status": "shipped",
-    "orderId": "order-123"
-  }
-}
-```
-
-**Not found (404):**
-```json
-{
-  "error": "Order not found",
-  "code": "ORDER_NOT_FOUND",
-  "details": { "id": "order-123" }
-}
-```
-
-**Generic error (500):**
-```json
-{
-  "error": "Internal server error",
-  "code": "INTERNAL_ERROR"
-}
-```
-
-### Error Code Convention
-
-Use SCREAMING_SNAKE_CASE for error codes:
-- `VALIDATION_ERROR` - Input validation failed
-- `ORDER_NOT_FOUND` - Resource not found
-- `ORDER_ALREADY_SHIPPED` - State violation
-- `INSUFFICIENT_INVENTORY` - Business rule violation
-- `AUTHENTICATION_REQUIRED` - Auth failed
-- `PERMISSION_DENIED` - Authz failed
-
-## Versioning Patterns
-
-### URL Versioning
-
-**Include version in path:**
-```
-GET /v1/orders
-GET /v2/orders
-```
-
-**Pros:** Explicit, clear to consumers
-**Cons:** Requires multiple code paths
-
-### Accept Header Versioning
-
-**Use media type version:**
-```
-GET /orders
-Accept: application/vnd.myapi.v2+json
-```
-
-**Pros:** Cleaner URLs, single endpoint
-**Cons:** Less discoverable
-
-### Pragmatic Approach
-
-1. Start without versioning (all responses same format)
-2. Add versioning when you need breaking changes
-3. Support at least 2 versions during transition
-4. Provide clear deprecation timeline
-
-### Backwards Compatibility
-
-**Adding fields (safe):**
-```typescript
-// v1
-interface OrderResponse {
-  id: string;
-  total: number;
-}
-
-// v2 (backwards compatible)
-interface OrderResponse {
-  id: string;
-  total: number;
-  tax?: number;  // New optional field
-}
-```
-
-**Removing fields (breaking change):**
-```typescript
-// Requires new API version
-// v1 has 'total'
-// v2 has 'subtotal' and 'tax'
-```
-
-## Example: Complete Order API
-
-### Endpoints
-
-```
-POST /orders
-  Create order
-  Request: CreateOrderRequest
-  Response: 201 OrderResponse
-
-GET /orders
-  List orders
-  Query: ListOrdersQuery
-  Response: 200 ListOrdersResponse
-
-GET /orders/:id
-  Get order
-  Response: 200 OrderResponse
-
-PATCH /orders/:id
-  Update order
-  Request: UpdateOrderRequest
-  Response: 200 OrderResponse
-
-POST /orders/:id/cancel
-  Cancel order
-  Response: 200 OrderResponse
-
-DELETE /orders/:id
-  Delete order
-  Response: 204 (no body)
-```
-
-### Implementation Pattern
-
-```typescript
-// Router handles HTTP concerns
-router.post('/orders', async (req, res) => {
-  // 1. Parse request
-  const request: CreateOrderRequest = req.body;
-
-  // 2. Validate input (preliminary)
-  if (!request.customerId) {
-    return res.status(400).json({
-      error: 'Validation failed',
-      code: 'VALIDATION_ERROR',
-      details: [{ field: 'customerId', message: 'Required' }]
-    });
-  }
-
-  // 3. Call service
-  const result = await orderService.createOrder(request);
-
-  // 4. Handle result
-  if (result.ok) {
-    return res.status(201).json(result.value.toResponse());
-  }
-
-  // 5. Return error
-  res.status(409).json({
-    error: result.error,
-    code: result.code || 'UNKNOWN_ERROR'
-  });
-});
-```

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 };
-}
-```