wicked-garden 12.27.0

package/skills/engineering/integration/refs/event-schemas-event-structure.md

@@ -0,0 +1,288 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Event Schema Design Guide: Event Structure
+
+## Event Structure
+
+### Core Components
+
+Every event should include:
+
+1. **Event Metadata**: Type, ID, timestamp, version
+2. **Event Payload**: Business data
+3. **Context**: Trace ID, correlation ID, source
+4. **Schema Information**: Version, format
+
+### Standard Event Envelope
+
+```json
+{
+  "id": "evt_1234567890",
+  "type": "order.created",
+  "version": "1.0",
+  "timestamp": "2025-01-24T10:00:00.000Z",
+  "source": "order-service",
+  "subject": "orders/12345",
+  "dataContentType": "application/json",
+  "data": {
+    "orderId": "12345",
+    "customerId": "customer-456",
+    "items": [...],
+    "total": 99.99
+  },
+  "metadata": {
+    "correlationId": "corr-abc-123",
+    "traceId": "trace-xyz-789",
+    "causationId": "evt_0987654321",
+    "userId": "user-123"
+  }
+}
+```
+
+## Event Types
+
+### Domain Events
+
+Business occurrences that have already happened (past tense).
+
+```json
+{
+  "type": "order.created",
+  "version": "1.0",
+  "timestamp": "2025-01-24T10:00:00.000Z",
+  "source": "order-service",
+  "data": {
+    "orderId": "order-12345",
+    "customerId": "customer-456",
+    "status": "pending",
+    "items": [
+      {
+        "productId": "prod-789",
+        "quantity": 2,
+        "price": 29.99
+      }
+    ],
+    "subtotal": 59.98,
+    "tax": 5.40,
+    "total": 65.38,
+    "currency": "USD",
+    "createdAt": "2025-01-24T10:00:00.000Z"
+  }
+}
+```
+
+### Command Events
+
+Requests for action (imperative).
+
+```json
+{
+  "type": "order.process",
+  "version": "1.0",
+  "timestamp": "2025-01-24T10:01:00.000Z",
+  "source": "checkout-service",
+  "data": {
+    "orderId": "order-12345",
+    "paymentMethod": {
+      "type": "credit_card",
+      "last4": "4242"
+    }
+  },
+  "metadata": {
+    "requestedBy": "user-123",
+    "correlationId": "corr-abc-123"
+  }
+}
+```
+
+### Integration Events
+
+Cross-service communication.
+
+```json
+{
+  "type": "payment.completed",
+  "version": "1.0",
+  "timestamp": "2025-01-24T10:02:00.000Z",
+  "source": "payment-service",
+  "data": {
+    "paymentId": "pay-xyz-789",
+    "orderId": "order-12345",
+    "amount": 65.38,
+    "currency": "USD",
+    "status": "succeeded",
+    "transactionId": "txn-abc-123"
+  }
+}
+```
+
+### State Change Events
+
+Object state transitions.
+
+```json
+{
+  "type": "order.status.changed",
+  "version": "1.0",
+  "timestamp": "2025-01-24T10:03:00.000Z",
+  "source": "order-service",
+  "data": {
+    "orderId": "order-12345",
+    "previousStatus": "pending",
+    "newStatus": "processing",
+    "changedAt": "2025-01-24T10:03:00.000Z",
+    "changedBy": "system"
+  }
+}
+```
+
+## Schema Formats
+
+### JSON Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/events/order-created.schema.json",
+  "title": "OrderCreated",
+  "description": "Event published when a new order is created",
+  "type": "object",
+  "required": ["type", "version", "timestamp", "source", "data"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "order.created"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source": {
+      "type": "string"
+    },
+    "data": {
+      "type": "object",
+      "required": ["orderId", "customerId", "items", "total"],
+      "properties": {
+        "orderId": {
+          "type": "string",
+          "pattern": "^order-[a-z0-9]+$"
+        },
+        "customerId": {
+          "type": "string"
+        },
+        "items": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["productId", "quantity", "price"],
+            "properties": {
+              "productId": {"type": "string"},
+              "quantity": {"type": "integer", "minimum": 1},
+              "price": {"type": "number", "minimum": 0}
+            }
+          }
+        },
+        "total": {
+          "type": "number",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "default": "USD"
+        }
+      }
+    }
+  }
+}
+```
+
+### Avro Schema
+
+```json
+{
+  "type": "record",
+  "name": "OrderCreated",
+  "namespace": "com.example.events",
+  "doc": "Event published when a new order is created",
+  "fields": [
+    {
+      "name": "eventId",
+      "type": "string",
+      "doc": "Unique event identifier"
+    },
+    {
+      "name": "timestamp",
+      "type": "long",
+      "logicalType": "timestamp-millis"
+    },
+    {
+      "name": "orderId",
+      "type": "string"
+    },
+    {
+      "name": "customerId",
+      "type": "string"
+    },
+    {
+      "name": "items",
+      "type": {
+        "type": "array",
+        "items": {
+          "type": "record",
+          "name": "OrderItem",
+          "fields": [
+            {"name": "productId", "type": "string"},
+            {"name": "quantity", "type": "int"},
+            {"name": "price", "type": "double"}
+          ]
+        }
+      }
+    },
+    {
+      "name": "total",
+      "type": "double"
+    },
+    {
+      "name": "currency",
+      "type": "string",
+      "default": "USD"
+    }
+  ]
+}
+```
+
+### Protocol Buffers
+
+```protobuf
+syntax = "proto3";
+
+package events.v1;
+
+import "google/protobuf/timestamp.proto";
+
+message OrderCreated {
+  string event_id = 1;
+  google.protobuf.Timestamp timestamp = 2;
+  string order_id = 3;
+  string customer_id = 4;
+  repeated OrderItem items = 5;
+  double total = 6;
+  string currency = 7;
+}
+
+message OrderItem {
+  string product_id = 1;
+  int32 quantity = 2;
+  double price = 3;
+}
+```
+

package/skills/engineering/integration/refs/graphql-best-practices.md

@@ -0,0 +1,138 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# GraphQL API Design Guide: Best Practices
+
+## Best Practices
+
+### 1. Schema-First Design
+
+Design schema before implementation. It's your API contract.
+
+### 2. Nullable by Default
+
+Make fields nullable unless they're truly required. Prevents breaking changes.
+
+```graphql
+# Good
+type User {
+  name: String  # Can add later without breaking
+}
+
+# Risky
+type User {
+  name: String! # Can't make nullable later
+}
+```
+
+### 3. Use Enums
+
+```graphql
+enum UserRole {
+  ADMIN
+  USER
+  GUEST
+}
+
+# Better than String
+```
+
+### 4. Input Types for Mutations
+
+```graphql
+# Good
+input CreateUserInput {
+  name: String!
+  email: String!
+}
+
+mutation {
+  createUser(input: CreateUserInput!): User
+}
+
+# Avoid
+mutation {
+  createUser(name: String!, email: String!): User
+}
+```
+
+### 5. Pagination for Lists
+
+Always paginate collections. Use Connection pattern.
+
+### 6. Descriptive Names
+
+```graphql
+# Good
+type Query {
+  user(id: ID!): User
+  userByEmail(email: String!): User
+}
+
+# Avoid
+type Query {
+  get(id: ID!): User
+  fetch(email: String!): User
+}
+```
+
+### 7. Document Your Schema
+
+```graphql
+"""
+Represents a user in the system.
+"""
+type User {
+  """
+  Unique identifier for the user.
+  """
+  id: ID!
+
+  """
+  User's email address. Must be unique.
+  """
+  email: String!
+}
+```
+
+### 8. Versioning
+
+Evolve schema without breaking changes:
+- Add new fields (nullable)
+- Deprecate old fields
+- Never remove fields abruptly
+
+```graphql
+type User {
+  oldField: String @deprecated(reason: "Use newField instead")
+  newField: String
+}
+```
+
+### 9. Error Handling in Payload
+
+Return errors as part of mutation payload, not just top-level errors.
+
+### 10. Testing
+
+Test resolvers thoroughly, including error cases.
+
+```typescript
+describe('User resolver', () => {
+  it('returns user by id', async () => {
+    const result = await resolvers.Query.user(
+      null,
+      { id: '123' },
+      { db: mockDb }
+    );
+    expect(result).toEqual({ id: '123', name: 'Alice' });
+  });
+
+  it('throws when user not found', async () => {
+    await expect(
+      resolvers.Query.user(null, { id: '999' }, { db: mockDb })
+    ).rejects.toThrow('User not found');
+  });
+});
+```

package/skills/engineering/integration/refs/graphql-error-handling.md

@@ -0,0 +1,198 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# GraphQL API Design Guide: Error Handling
+
+## Error Handling
+
+### Field-Level Errors
+
+```graphql
+type CreateUserPayload {
+  success: Boolean!
+  user: User
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String    # Which input field caused error
+  message: String!
+  code: String!    # Machine-readable error code
+}
+```
+
+### Top-Level Errors
+
+```json
+{
+  "errors": [
+    {
+      "message": "Unauthorized",
+      "extensions": {
+        "code": "UNAUTHENTICATED",
+        "timestamp": "2025-01-24T10:00:00Z"
+      },
+      "path": ["currentUser"]
+    }
+  ],
+  "data": {
+    "currentUser": null
+  }
+}
+```
+
+### Custom Error Codes
+
+```typescript
+class AuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.extensions = {
+      code: 'UNAUTHENTICATED',
+    };
+  }
+}
+
+class ValidationError extends Error {
+  constructor(message: string, field: string) {
+    super(message);
+    this.extensions = {
+      code: 'VALIDATION_ERROR',
+      field,
+    };
+  }
+}
+
+// In resolver
+if (!context.userId) {
+  throw new AuthenticationError('Must be logged in');
+}
+```
+
+## Security
+
+### Authentication
+
+```typescript
+const resolvers = {
+  Query: {
+    currentUser: async (parent, args, context) => {
+      // Check authentication
+      if (!context.userId) {
+        throw new AuthenticationError('Not authenticated');
+      }
+      return await db.users.findById(context.userId);
+    },
+  },
+};
+
+// Context from request
+const context = ({ req }) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  const userId = verifyToken(token);
+  return { userId, db };
+};
+```
+
+### Authorization
+
+```typescript
+const resolvers = {
+  Mutation: {
+    deletePost: async (parent, args: { id: string }, context) => {
+      const post = await db.posts.findById(args.id);
+
+      // Check authorization
+      if (post.authorId !== context.userId) {
+        throw new ForbiddenError('Not authorized to delete this post');
+      }
+
+      await db.posts.delete(args.id);
+      return { success: true };
+    },
+  },
+};
+```
+
+### Query Depth Limiting
+
+```typescript
+import { createComplexityLimitRule } from 'graphql-validation-complexity';
+
+const complexityLimit = createComplexityLimitRule(1000, {
+  scalarCost: 1,
+  objectCost: 5,
+  listFactor: 10,
+});
+
+const server = new ApolloServer({
+  schema,
+  validationRules: [complexityLimit],
+});
+```
+
+### Query Cost Analysis
+
+```typescript
+const costAnalysis = {
+  Query: {
+    users: { complexity: ({ args }) => args.limit * 5 },
+    posts: { complexity: ({ args }) => args.limit * 10 },
+  },
+  User: {
+    posts: { complexity: 10 },
+  },
+};
+```
+
+## Performance Optimization
+
+### DataLoader (Batching)
+
+Batch multiple requests into single database query.
+
+### Query Complexity Analysis
+
+Prevent expensive queries:
+```typescript
+// Too complex - would make 1000s of queries
+query ExpensiveQuery {
+  users(limit: 100) {
+    posts(limit: 100) {
+      comments(limit: 100) {
+        author {
+          posts(limit: 100) {
+            # ...
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Persisted Queries
+
+Pre-register queries, send only hash:
+```graphql
+# Client sends
+{ "id": "abc123", "variables": { "limit": 10 } }
+
+# Instead of full query
+```
+
+### Caching
+
+```typescript
+// Field-level cache hints
+type User {
+  id: ID!
+  name: String! @cacheControl(maxAge: 3600)
+  email: String! @cacheControl(maxAge: 0) # Private
+}
+
+// HTTP caching
+res.set('Cache-Control', 'public, max-age=3600');
+```
+