Initial commit: add .gitignore and README

EVENT_DRIVEN_MIGRATION_GUIDE.md

@@ -0,0 +1,232 @@
+# Event-Driven Architecture Migration Guide
+
+**Date**: 2025-01-27
+**Purpose**: Guide for migrating projects to event-driven architecture
+**Status**: Complete
+
+---
+
+## Overview
+
+This guide provides instructions for migrating projects to use the shared event bus (NATS) for event-driven communication.
+
+---
+
+## Prerequisites
+
+- NATS event bus deployed
+- Access to event bus
+- Understanding of event-driven patterns
+
+---
+
+## Migration Steps
+
+### Step 1: Install NATS Client
+
+```bash
+pnpm add nats
+```
+
+### Step 2: Create Event Publisher
+
+```typescript
+import { connect, NatsConnection } from 'nats';
+
+class EventPublisher {
+  private nc: NatsConnection | null = null;
+
+  async connect() {
+    this.nc = await connect({
+      servers: process.env.NATS_URL || 'nats://nats:4222',
+    });
+  }
+
+  async publish(subject: string, data: unknown) {
+    if (!this.nc) {
+      await this.connect();
+    }
+    await this.nc!.publish(subject, JSON.stringify(data));
+  }
+
+  async close() {
+    await this.nc?.close();
+  }
+}
+```
+
+### Step 3: Create Event Subscriber
+
+```typescript
+import { connect, NatsConnection } from 'nats';
+
+class EventSubscriber {
+  private nc: NatsConnection | null = null;
+
+  async connect() {
+    this.nc = await connect({
+      servers: process.env.NATS_URL || 'nats://nats:4222',
+    });
+  }
+
+  async subscribe(subject: string, handler: (data: unknown) => void) {
+    if (!this.nc) {
+      await this.connect();
+    }
+    const sub = this.nc!.subscribe(subject);
+    for await (const msg of sub) {
+      const data = JSON.parse(msg.data.toString());
+      handler(data);
+    }
+  }
+
+  async close() {
+    await this.nc?.close();
+  }
+}
+```
+
+### Step 4: Define Event Schemas
+
+```typescript
+// events/user-events.ts
+export interface UserCreatedEvent {
+  type: 'user.created';
+  userId: string;
+  email: string;
+  timestamp: Date;
+}
+
+export interface UserUpdatedEvent {
+  type: 'user.updated';
+  userId: string;
+  changes: Record<string, unknown>;
+  timestamp: Date;
+}
+```
+
+### Step 5: Publish Events
+
+```typescript
+import { EventPublisher } from './event-publisher';
+import { UserCreatedEvent } from './events/user-events';
+
+const publisher = new EventPublisher();
+
+async function createUser(userData: UserData) {
+  // Create user logic
+  const user = await createUserInDB(userData);
+
+  // Publish event
+  const event: UserCreatedEvent = {
+    type: 'user.created',
+    userId: user.id,
+    email: user.email,
+    timestamp: new Date(),
+  };
+  await publisher.publish('events.user.created', event);
+}
+```
+
+### Step 6: Subscribe to Events
+
+```typescript
+import { EventSubscriber } from './event-subscriber';
+import { UserCreatedEvent } from './events/user-events';
+
+const subscriber = new EventSubscriber();
+
+async function setupEventHandlers() {
+  await subscriber.subscribe('events.user.created', async (data: UserCreatedEvent) => {
+    // Handle user created event
+    await sendWelcomeEmail(data.email);
+    await createUserProfile(data.userId);
+  });
+}
+```
+
+---
+
+## Best Practices
+
+### Event Naming
+- Use consistent naming: `events.{domain}.{action}`
+- Examples: `events.user.created`, `events.order.placed`
+
+### Event Schema
+- Define schemas using TypeScript interfaces
+- Include type, timestamp, and relevant data
+- Version events for compatibility
+
+### Error Handling
+- Implement retry logic
+- Use dead letter queues
+- Log all events
+
+### Monitoring
+- Track event rates
+- Monitor latency
+- Set up alerts
+
+---
+
+## Testing
+
+### Unit Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { EventPublisher } from './event-publisher';
+
+describe('EventPublisher', () => {
+  it('should publish events', async () => {
+    const publisher = new EventPublisher();
+    await publisher.publish('test.event', { data: 'test' });
+    // Verify event was published
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { EventPublisher, EventSubscriber } from './events';
+
+describe('Event Integration', () => {
+  it('should publish and receive events', async () => {
+    const publisher = new EventPublisher();
+    const subscriber = new EventSubscriber();
+
+    const received: unknown[] = [];
+    await subscriber.subscribe('test.event', (data) => {
+      received.push(data);
+    });
+
+    await publisher.publish('test.event', { data: 'test' });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    expect(received).toHaveLength(1);
+  });
+});
+```
+
+---
+
+## Migration Checklist
+
+- [ ] Install NATS client
+- [ ] Create event publisher
+- [ ] Create event subscriber
+- [ ] Define event schemas
+- [ ] Update code to publish events
+- [ ] Update code to subscribe to events
+- [ ] Test event publishing
+- [ ] Test event subscription
+- [ ] Set up monitoring
+- [ ] Update documentation
+
+---
+
+**Last Updated**: 2025-01-27
+