@garethdaine/agentops 0.9.0

package/templates/architecture/event-driven.md

@@ -0,0 +1,252 @@
+# Architecture Pattern: Event-Driven Architecture
+
+## When to Use
+
+- Decoupling producers from consumers so they can evolve independently
+- Processing that can tolerate eventual consistency (order fulfilment, notifications, analytics)
+- Fan-out scenarios where one action triggers multiple downstream reactions
+- Replacing synchronous chains that create fragile coupling between services
+
+## Pattern Description
+
+Event-driven architecture uses events as the primary communication mechanism between components. A producer emits an event describing something that happened. One or more consumers react to that event independently. The producer does not know (or care) who consumes the event or what they do with it.
+
+## Event Schema Design (CloudEvents)
+
+Use a standardised envelope to ensure interoperability across services:
+
+```typescript
+/**
+ * CloudEvents-compliant event envelope.
+ * See https://cloudevents.io for the full specification.
+ */
+export interface DomainEvent<T = unknown> {
+  /** Unique event identifier */
+  id: string;
+  /** Reverse-DNS event type, e.g. 'com.acme.order.created' */
+  type: string;
+  /** Event origin, e.g. 'orders-service' */
+  source: string;
+  /** CloudEvents spec version */
+  specversion: '1.0';
+  /** ISO 8601 timestamp */
+  time: string;
+  /** Content type of the data payload */
+  datacontenttype: 'application/json';
+  /** The event payload */
+  data: T;
+  /** Optional: subject the event relates to */
+  subject?: string;
+}
+
+// Factory function for consistent event creation
+export function createEvent<T>(
+  type: string,
+  source: string,
+  data: T,
+  subject?: string,
+): DomainEvent<T> {
+  return {
+    id: crypto.randomUUID(),
+    type,
+    source,
+    specversion: '1.0',
+    time: new Date().toISOString(),
+    datacontenttype: 'application/json',
+    data,
+    subject,
+  };
+}
+```
+
+## Event Bus Abstraction
+
+```typescript
+export interface EventBus {
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(eventType: string, handler: EventHandler): void;
+}
+
+export type EventHandler<T = unknown> = (event: DomainEvent<T>) => Promise<void>;
+
+/**
+ * In-memory implementation for development and testing.
+ * Swap for SQS/EventBridge/Redis Streams in production.
+ */
+export class InMemoryEventBus implements EventBus {
+  private handlers = new Map<string, EventHandler[]>();
+
+  async publish(event: DomainEvent): Promise<void> {
+    const subscribers = this.handlers.get(event.type) ?? [];
+    await Promise.allSettled(subscribers.map((h) => h(event)));
+  }
+
+  subscribe(eventType: string, handler: EventHandler): void {
+    const existing = this.handlers.get(eventType) ?? [];
+    this.handlers.set(eventType, [...existing, handler]);
+  }
+}
+```
+
+## Idempotency
+
+Consumers must handle receiving the same event more than once. At-least-once delivery is the norm for most message systems.
+
+```typescript
+export class IdempotentHandler<T> {
+  constructor(
+    private store: IdempotencyStore,
+    private handler: EventHandler<T>,
+  ) {}
+
+  async handle(event: DomainEvent<T>): Promise<void> {
+    const alreadyProcessed = await this.store.exists(event.id);
+    if (alreadyProcessed) {
+      logger.info('Skipping duplicate event', { eventId: event.id });
+      return;
+    }
+
+    await this.handler(event);
+    await this.store.markProcessed(event.id, { ttlSeconds: 86400 * 7 });
+  }
+}
+
+export interface IdempotencyStore {
+  exists(eventId: string): Promise<boolean>;
+  markProcessed(eventId: string, options?: { ttlSeconds: number }): Promise<void>;
+}
+
+// Redis-backed implementation
+export class RedisIdempotencyStore implements IdempotencyStore {
+  constructor(private redis: RedisClient) {}
+
+  async exists(eventId: string): Promise<boolean> {
+    const result = await this.redis.get(`idempotency:${eventId}`);
+    return result !== null;
+  }
+
+  async markProcessed(eventId: string, options?: { ttlSeconds: number }): Promise<void> {
+    await this.redis.set(`idempotency:${eventId}`, '1', { EX: options?.ttlSeconds ?? 604800 });
+  }
+}
+```
+
+## Dead Letter Queue Handling
+
+When a consumer fails repeatedly, move the event to a dead letter queue for manual inspection:
+
+```typescript
+export class RetryableConsumer<T> {
+  constructor(
+    private handler: EventHandler<T>,
+    private dlq: DeadLetterQueue,
+    private maxRetries: number = 3,
+  ) {}
+
+  async process(event: DomainEvent<T>, attemptCount: number): Promise<void> {
+    try {
+      await this.handler(event);
+    } catch (error) {
+      if (attemptCount >= this.maxRetries) {
+        logger.error('Max retries exceeded, sending to DLQ', {
+          eventId: event.id,
+          eventType: event.type,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        await this.dlq.send(event, {
+          error: error instanceof Error ? error.message : String(error),
+          attempts: attemptCount,
+          failedAt: new Date().toISOString(),
+        });
+        return;
+      }
+      throw error; // Let the queue infrastructure retry
+    }
+  }
+}
+
+export interface DeadLetterQueue {
+  send(event: DomainEvent, metadata: Record<string, unknown>): Promise<void>;
+}
+```
+
+## Event Ordering Guarantees
+
+Most message systems guarantee ordering only within a partition or message group:
+
+```typescript
+/**
+ * Use a consistent partition key so events for the same entity
+ * are processed in order.
+ *
+ * SQS FIFO: MessageGroupId
+ * Kafka: partition key
+ * Redis Streams: stream key
+ */
+export function publishOrderEvent(event: DomainEvent<OrderData>): Promise<void> {
+  return queue.send({
+    body: JSON.stringify(event),
+    // All events for the same order go to the same partition
+    messageGroupId: event.data.orderId,
+    // Deduplication ID for exactly-once in FIFO queues
+    messageDeduplicationId: event.id,
+  });
+}
+```
+
+## Saga / Choreography Pattern
+
+Coordinate multi-step workflows through event chains rather than a central orchestrator:
+
+```typescript
+/**
+ * Example: Order fulfilment saga via choreography
+ *
+ * 1. OrderService emits 'order.placed'
+ * 2. PaymentService listens, charges card, emits 'payment.captured'
+ * 3. InventoryService listens, reserves stock, emits 'inventory.reserved'
+ * 4. ShippingService listens, creates shipment, emits 'shipment.created'
+ *
+ * Compensating actions if any step fails:
+ * - 'payment.failed'  -> OrderService cancels the order
+ * - 'inventory.insufficient' -> PaymentService refunds, OrderService cancels
+ */
+
+// Payment service consumer
+eventBus.subscribe('order.placed', async (event: DomainEvent<OrderPlaced>) => {
+  try {
+    const payment = await paymentService.charge(event.data.paymentMethodId, event.data.total);
+    await eventBus.publish(createEvent('payment.captured', 'payment-service', {
+      orderId: event.data.orderId,
+      paymentId: payment.id,
+    }));
+  } catch (error) {
+    await eventBus.publish(createEvent('payment.failed', 'payment-service', {
+      orderId: event.data.orderId,
+      reason: error instanceof Error ? error.message : 'Unknown error',
+    }));
+  }
+});
+
+// Order service listens for compensation
+eventBus.subscribe('payment.failed', async (event: DomainEvent<PaymentFailed>) => {
+  await orderService.cancel(event.data.orderId, event.data.reason);
+});
+```
+
+## Trade-offs
+
+- **Eventual consistency:** Consumers process events asynchronously. The system is not immediately consistent after a write.
+- **Debugging difficulty:** Tracing a request across event chains requires correlation IDs and distributed tracing.
+- **Ordering complexity:** Global ordering is expensive. Design for partition-level ordering or tolerate out-of-order delivery.
+- **Schema evolution:** Changing event shapes requires versioning and backward-compatible consumers.
+- **Operational overhead:** Dead letter queues, retry policies, and monitoring infrastructure must be maintained.
+
+## Common Pitfalls
+
+1. **Fat events with too much data** — Include only what consumers need. Large payloads increase coupling and bandwidth costs.
+2. **Missing idempotency** — At-least-once delivery means duplicates will happen. Every consumer must handle them.
+3. **Synchronous event processing disguised as async** — Publishing an event and then polling for the result defeats the purpose.
+4. **No dead letter queue** — Failed events that disappear silently cause data loss.
+5. **Tight schema coupling** — Consumers that break when a new field is added to an event are too tightly coupled. Use tolerant readers.
+6. **Ignoring backpressure** — A fast producer can overwhelm a slow consumer. Use queue depth monitoring and rate limiting.

package/templates/architecture/integration-patterns.md

@@ -0,0 +1,185 @@
+# Architecture Pattern: Integration Patterns
+
+## Adapter Pattern
+
+The primary pattern for integrating with external systems. Protects your domain from external API changes.
+
+### Interface Definition
+
+```typescript
+/**
+ * Define a typed interface for every external system integration.
+ * This is the contract your domain depends on — NOT the external API shape.
+ */
+export interface ProcurementAdapter {
+  getOrders(tenantId: string, filters?: OrderFilters): Promise<PaginatedResult<Order>>;
+  getOrderById(tenantId: string, orderId: string): Promise<Order | null>;
+  createOrder(tenantId: string, data: CreateOrderInput): Promise<Order>;
+  updateOrderStatus(tenantId: string, orderId: string, status: OrderStatus): Promise<Order>;
+}
+
+export interface OrderFilters {
+  status?: OrderStatus;
+  dateFrom?: Date;
+  dateTo?: Date;
+  limit?: number;
+  offset?: number;
+}
+```
+
+### Mock Implementation
+
+```typescript
+/**
+ * Mock adapter for development and testing.
+ * Returns realistic data without hitting external APIs.
+ */
+export class MockProcurementAdapter implements ProcurementAdapter {
+  private orders: Map<string, Order[]> = new Map();
+
+  async getOrders(tenantId: string, filters?: OrderFilters): Promise<PaginatedResult<Order>> {
+    const tenantOrders = this.orders.get(tenantId) ?? this.seedData(tenantId);
+    // Apply filters, pagination...
+    return { data: tenantOrders, total: tenantOrders.length, limit: 20, offset: 0 };
+  }
+
+  // ... implement all interface methods with in-memory data
+}
+```
+
+### Real Implementation
+
+```typescript
+/**
+ * Real adapter calling the external procurement API.
+ * Handles auth, retries, error mapping, and response transformation.
+ */
+export class HttpProcurementAdapter implements ProcurementAdapter {
+  constructor(
+    private baseUrl: string,
+    private apiKey: string,
+    private httpClient: HttpClient,
+  ) {}
+
+  async getOrders(tenantId: string, filters?: OrderFilters): Promise<PaginatedResult<Order>> {
+    const response = await this.httpClient.get(`${this.baseUrl}/orders`, {
+      headers: { 'X-Tenant-ID': tenantId, Authorization: `Bearer ${this.apiKey}` },
+      params: this.mapFilters(filters),
+    });
+    return this.mapResponse(response.data);
+  }
+
+  /** Map external API response to domain model */
+  private mapResponse(external: ExternalOrderResponse): PaginatedResult<Order> {
+    return {
+      data: external.items.map(this.mapOrder),
+      total: external.totalCount,
+      limit: external.pageSize,
+      offset: external.page * external.pageSize,
+    };
+  }
+}
+```
+
+### Factory / DI Registration
+
+```typescript
+export function createProcurementAdapter(): ProcurementAdapter {
+  if (env.NODE_ENV === 'test' || env.USE_MOCK_ADAPTERS === 'true') {
+    return new MockProcurementAdapter();
+  }
+  return new HttpProcurementAdapter(env.PROCUREMENT_API_URL, env.PROCUREMENT_API_KEY, httpClient);
+}
+```
+
+## Anti-Corruption Layer
+
+Prevent external API models from leaking into your domain:
+- Define your own domain types (never use external response types directly)
+- Map at the adapter boundary
+- Validate external responses before mapping
+- Handle missing/unexpected fields gracefully
+
+## Circuit Breaker Pattern
+
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailure?: Date;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+
+  constructor(
+    private threshold: number = 5,
+    private resetTimeoutMs: number = 30_000,
+  ) {}
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailure!.getTime() > this.resetTimeoutMs) {
+        this.state = 'half-open';
+      } else {
+        throw new AppError('Service unavailable (circuit open)', { statusCode: 503 });
+      }
+    }
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+}
+```
+
+## Retry Policy
+
+```typescript
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries: number; backoffMs: number; retryableErrors?: string[] },
+): Promise<T> {
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === options.maxRetries) throw error;
+      const isRetryable = error instanceof AppError && error.statusCode >= 500;
+      if (!isRetryable) throw error;
+      await sleep(options.backoffMs * Math.pow(2, attempt));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+## Contract Testing
+
+```typescript
+/**
+ * Contract tests verify that both mock and real adapters behave identically.
+ * Run against mock in CI, against real in integration environment.
+ */
+describe('ProcurementAdapter contract', () => {
+  const adapters = [
+    ['mock', new MockProcurementAdapter()],
+    // ['real', new HttpProcurementAdapter(...)],  // Enable in integration env
+  ] as const;
+
+  adapters.forEach(([name, adapter]) => {
+    describe(name, () => {
+      it('should return paginated orders for a tenant', async () => {
+        const result = await adapter.getOrders('tenant-1');
+        expect(result.data).toBeInstanceOf(Array);
+        expect(result.total).toBeGreaterThanOrEqual(0);
+      });
+
+      it('should return null for non-existent order', async () => {
+        const result = await adapter.getOrderById('tenant-1', 'non-existent');
+        expect(result).toBeNull();
+      });
+    });
+  });
+});
+```

package/templates/architecture/multi-tenancy.md

@@ -0,0 +1,104 @@
+# Architecture Pattern: Multi-Tenancy
+
+## Tenant Context Propagation
+
+Every request must carry tenant context. Extract once at the edge, propagate through the entire request lifecycle.
+
+### Middleware
+
+```typescript
+export function tenantMiddleware(req: Request, res: Response, next: NextFunction) {
+  const tenantId = req.headers['x-tenant-id'] as string;
+  if (!tenantId) {
+    throw new AuthenticationError('Tenant ID required');
+  }
+  // Validate tenant exists and is active
+  req.tenantId = tenantId;
+  next();
+}
+```
+
+### AsyncLocalStorage for Deep Propagation
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+interface TenantContext {
+  tenantId: string;
+  userId?: string;
+  permissions?: string[];
+}
+
+export const tenantStore = new AsyncLocalStorage<TenantContext>();
+
+export function getCurrentTenant(): TenantContext {
+  const ctx = tenantStore.getStore();
+  if (!ctx) throw new Error('No tenant context — ensure tenantMiddleware is applied');
+  return ctx;
+}
+```
+
+## Database Isolation Strategies
+
+### Row-Level Security (Recommended)
+
+```sql
+-- Every table has a tenant_id column
+ALTER TABLE orders ADD COLUMN tenant_id TEXT NOT NULL;
+CREATE INDEX idx_orders_tenant ON orders(tenant_id);
+
+-- Prisma: always filter by tenant
+const orders = await prisma.order.findMany({
+  where: { tenantId: getCurrentTenant().tenantId, ...filters },
+});
+```
+
+### Query Scoping Pattern
+
+```typescript
+/** Base repository that automatically scopes all queries by tenant */
+export class TenantScopedRepository<T> {
+  constructor(private model: PrismaModel<T>) {}
+
+  async findMany(where: Partial<T>): Promise<T[]> {
+    const { tenantId } = getCurrentTenant();
+    return this.model.findMany({ where: { ...where, tenantId } });
+  }
+
+  async create(data: Omit<T, 'tenantId'>): Promise<T> {
+    const { tenantId } = getCurrentTenant();
+    return this.model.create({ data: { ...data, tenantId } });
+  }
+}
+```
+
+## Data Leakage Prevention
+
+1. **Never trust client-provided tenant IDs for data access** — always derive from auth token
+2. **Audit cross-tenant queries** — log and alert on any query that doesn't include tenant scoping
+3. **Test isolation** — write tests that verify tenant A cannot see tenant B's data
+4. **API response validation** — verify responses only contain data for the requesting tenant
+
+## Tenant-Aware Caching
+
+```typescript
+function cacheKey(key: string): string {
+  const { tenantId } = getCurrentTenant();
+  return `tenant:${tenantId}:${key}`;
+}
+```
+
+## Testing Multi-Tenancy
+
+```typescript
+describe('tenant isolation', () => {
+  it('should not return orders from other tenants', async () => {
+    await createOrder({ tenantId: 'tenant-a', item: 'Widget A' });
+    await createOrder({ tenantId: 'tenant-b', item: 'Widget B' });
+
+    const result = await getOrders('tenant-a');
+    expect(result.every((o) => o.tenantId === 'tenant-a')).toBe(true);
+    expect(result.some((o) => o.item === 'Widget B')).toBe(false);
+  });
+});
+```