Event-Driven Architecture Guide

# Event-Driven Architecture Guide for Google Antigravity

Master event-driven architecture patterns to build reactive, scalable applications with Google Antigravity IDE.

## Event Store Implementation

```typescript
// lib/event-store.ts
import { Pool } from "pg";
import { v4 as uuid } from "uuid";

interface DomainEvent {
  id: string;
  aggregateId: string;
  aggregateType: string;
  eventType: string;
  payload: Record<string, unknown>;
  metadata: { userId?: string; correlationId?: string; timestamp: Date };
  version: number;
}

export class EventStore {
  constructor(private pool: Pool) {}

  async append(events: Omit<DomainEvent, "id">[]): Promise<void> {
    const client = await this.pool.connect();
    
    try {
      await client.query("BEGIN");
      
      for (const event of events) {
        await client.query(
          `INSERT INTO events (id, aggregate_id, aggregate_type, event_type, payload, metadata, version)
           VALUES ($1, $2, $3, $4, $5, $6, $7)`,
          [uuid(), event.aggregateId, event.aggregateType, event.eventType, 
           JSON.stringify(event.payload), JSON.stringify(event.metadata), event.version]
        );
      }
      
      await client.query("COMMIT");
    } catch (error) {
      await client.query("ROLLBACK");
      throw error;
    } finally {
      client.release();
    }
  }

  async getEvents(aggregateId: string, fromVersion = 0): Promise<DomainEvent[]> {
    const result = await this.pool.query(
      `SELECT * FROM events WHERE aggregate_id = $1 AND version > $2 ORDER BY version ASC`,
      [aggregateId, fromVersion]
    );
    return result.rows;
  }

  async getEventsByType(eventType: string, limit = 100): Promise<DomainEvent[]> {
    const result = await this.pool.query(
      `SELECT * FROM events WHERE event_type = $1 ORDER BY metadata->'timestamp' DESC LIMIT $2`,
      [eventType, limit]
    );
    return result.rows;
  }
}
```

## Aggregate Root Pattern

```typescript
// domain/order.ts
abstract class AggregateRoot {
  protected uncommittedEvents: DomainEvent[] = [];
  protected version = 0;

  getUncommittedEvents(): DomainEvent[] {
    return [...this.uncommittedEvents];
  }

  clearUncommittedEvents(): void {
    this.uncommittedEvents = [];
  }

  protected addEvent(event: Omit<DomainEvent, "id" | "version">): void {
    this.version++;
    this.uncommittedEvents.push({ ...event, id: uuid(), version: this.version } as DomainEvent);
  }
}

export class Order extends AggregateRoot {
  private id: string;
  private status: "pending" | "confirmed" | "shipped" | "delivered" | "cancelled";
  private items: OrderItem[] = [];

  static create(customerId: string, items: OrderItem[]): Order {
    const order = new Order();
    order.apply({ type: "OrderCreated", customerId, items, orderId: uuid() });
    return order;
  }

  confirm(): void {
    if (this.status !== "pending") {
      throw new Error("Can only confirm pending orders");
    }
    this.apply({ type: "OrderConfirmed", orderId: this.id });
  }

  private apply(event: { type: string; [key: string]: unknown }): void {
    this.when(event);
    this.addEvent({
      aggregateId: this.id,
      aggregateType: "Order",
      eventType: event.type,
      payload: event,
      metadata: { timestamp: new Date() }
    });
  }

  private when(event: { type: string; [key: string]: unknown }): void {
    switch (event.type) {
      case "OrderCreated":
        this.id = event.orderId as string;
        this.status = "pending";
        this.items = event.items as OrderItem[];
        break;
      case "OrderConfirmed":
        this.status = "confirmed";
        break;
    }
  }
}
```

## Event Handlers and Projections

```typescript
// projections/order-projection.ts
export class OrderProjection {
  constructor(private db: Database) {}

  async handle(event: DomainEvent): Promise<void> {
    switch (event.eventType) {
      case "OrderCreated":
        await this.db.orders.insert({
          id: event.payload.orderId,
          customerId: event.payload.customerId,
          status: "pending",
          itemCount: (event.payload.items as unknown[]).length,
          createdAt: event.metadata.timestamp
        });
        break;
        
      case "OrderConfirmed":
        await this.db.orders.update(event.aggregateId, { 
          status: "confirmed", 
          confirmedAt: event.metadata.timestamp 
        });
        break;
    }
  }
}

// Event dispatcher
export class EventDispatcher {
  private handlers: Map<string, ((event: DomainEvent) => Promise<void>)[]> = new Map();

  register(eventType: string, handler: (event: DomainEvent) => Promise<void>): void {
    const existing = this.handlers.get(eventType) || [];
    this.handlers.set(eventType, [...existing, handler]);
  }

  async dispatch(event: DomainEvent): Promise<void> {
    const handlers = this.handlers.get(event.eventType) || [];
    await Promise.all(handlers.map(h => h(event)));
  }
}
```

## Best Practices

1. **Immutable events** that represent facts that happened
2. **Event versioning** for schema evolution
3. **Idempotent handlers** for at-least-once delivery
4. **Correlation IDs** for request tracing
5. **Snapshots** for performance optimization
6. **Event replay** capabilities for debugging
7. **Schema registry** for event contracts

Google Antigravity helps design event schemas and implement event sourcing patterns with intelligent code generation.