@aicgen/aicgen 1.0.0-beta.1

package/data/architecture/event-driven/messaging.md

@@ -0,0 +1,242 @@
+# Event-Driven Messaging
+
+## Message Types
+
+### Commands
+Request to perform an action. Directed to a single handler.
+
+```typescript
+interface CreateOrderCommand {
+  type: 'CreateOrder';
+  orderId: string;
+  customerId: string;
+  items: OrderItem[];
+  timestamp: Date;
+}
+
+// Single handler processes the command
+class CreateOrderHandler {
+  async handle(command: CreateOrderCommand): Promise<void> {
+    const order = Order.create(command);
+    await this.repository.save(order);
+    await this.eventBus.publish(new OrderCreatedEvent(order));
+  }
+}
+```
+
+### Events
+Notification that something happened. Published to multiple subscribers.
+
+```typescript
+interface OrderCreatedEvent {
+  type: 'OrderCreated';
+  orderId: string;
+  customerId: string;
+  totalAmount: number;
+  occurredAt: Date;
+}
+
+// Multiple handlers can subscribe
+class InventoryService {
+  @Subscribe('OrderCreated')
+  async onOrderCreated(event: OrderCreatedEvent): Promise<void> {
+    await this.reserveInventory(event.orderId);
+  }
+}
+
+class NotificationService {
+  @Subscribe('OrderCreated')
+  async onOrderCreated(event: OrderCreatedEvent): Promise<void> {
+    await this.sendConfirmation(event.customerId);
+  }
+}
+```
+
+### Queries
+Request for data. Returns a response.
+
+```typescript
+interface GetOrderQuery {
+  type: 'GetOrder';
+  orderId: string;
+}
+
+class GetOrderHandler {
+  async handle(query: GetOrderQuery): Promise<Order> {
+    return this.repository.findById(query.orderId);
+  }
+}
+```
+
+## Message Bus Patterns
+
+### In-Memory Bus
+
+```typescript
+class EventBus {
+  private handlers = new Map<string, Function[]>();
+
+  subscribe(eventType: string, handler: Function): void {
+    const handlers = this.handlers.get(eventType) || [];
+    handlers.push(handler);
+    this.handlers.set(eventType, handlers);
+  }
+
+  async publish(event: Event): Promise<void> {
+    const handlers = this.handlers.get(event.type) || [];
+    await Promise.all(handlers.map(h => h(event)));
+  }
+}
+```
+
+### Message Queue Integration
+
+```typescript
+// RabbitMQ example
+class RabbitMQPublisher {
+  async publish(event: Event): Promise<void> {
+    const message = JSON.stringify({
+      type: event.type,
+      data: event,
+      metadata: {
+        correlationId: uuid(),
+        timestamp: new Date().toISOString()
+      }
+    });
+
+    await this.channel.publish(
+      'events',
+      event.type,
+      Buffer.from(message),
+      { persistent: true }
+    );
+  }
+}
+
+class RabbitMQConsumer {
+  async consume(queue: string, handler: EventHandler): Promise<void> {
+    await this.channel.consume(queue, async (msg) => {
+      if (!msg) return;
+
+      try {
+        const event = JSON.parse(msg.content.toString());
+        await handler.handle(event);
+        this.channel.ack(msg);
+      } catch (error) {
+        this.channel.nack(msg, false, true); // Requeue
+      }
+    });
+  }
+}
+```
+
+## Delivery Guarantees
+
+### At-Least-Once Delivery
+
+```typescript
+// Producer: persist before publish
+async function publishWithRetry(event: Event): Promise<void> {
+  // 1. Save to outbox
+  await db.insert('outbox', {
+    id: event.id,
+    type: event.type,
+    payload: JSON.stringify(event),
+    status: 'pending'
+  });
+
+  // 2. Publish (may fail)
+  try {
+    await messageBus.publish(event);
+    await db.update('outbox', event.id, { status: 'sent' });
+  } catch {
+    // Retry worker will pick it up
+  }
+}
+
+// Consumer: idempotent handling
+async function handleIdempotent(event: Event): Promise<void> {
+  const processed = await db.findOne('processed_events', event.id);
+  if (processed) return; // Already handled
+
+  await handleEvent(event);
+  await db.insert('processed_events', { id: event.id });
+}
+```
+
+### Outbox Pattern
+
+```typescript
+// Transaction includes outbox write
+async function createOrder(data: OrderData): Promise<Order> {
+  return await db.transaction(async (tx) => {
+    // 1. Business logic
+    const order = Order.create(data);
+    await tx.insert('orders', order);
+
+    // 2. Outbox entry (same transaction)
+    await tx.insert('outbox', {
+      id: uuid(),
+      aggregateId: order.id,
+      type: 'OrderCreated',
+      payload: JSON.stringify(order)
+    });
+
+    return order;
+  });
+}
+
+// Separate process polls and publishes
+async function processOutbox(): Promise<void> {
+  const pending = await db.query(
+    'SELECT * FROM outbox WHERE status = $1 ORDER BY created_at LIMIT 100',
+    ['pending']
+  );
+
+  for (const entry of pending) {
+    await messageBus.publish(JSON.parse(entry.payload));
+    await db.update('outbox', entry.id, { status: 'sent' });
+  }
+}
+```
+
+## Dead Letter Queues
+
+```typescript
+class DeadLetterHandler {
+  maxRetries = 3;
+
+  async handleFailure(message: Message, error: Error): Promise<void> {
+    const retryCount = message.metadata.retryCount || 0;
+
+    if (retryCount < this.maxRetries) {
+      // Retry with backoff
+      await this.scheduleRetry(message, retryCount + 1);
+    } else {
+      // Move to DLQ
+      await this.moveToDLQ(message, error);
+    }
+  }
+
+  async moveToDLQ(message: Message, error: Error): Promise<void> {
+    await this.dlqChannel.publish('dead-letter', {
+      originalMessage: message,
+      error: error.message,
+      failedAt: new Date()
+    });
+
+    // Alert operations
+    await this.alerting.notify('Message moved to DLQ', { message, error });
+  }
+}
+```
+
+## Best Practices
+
+- Use correlation IDs to trace message flows
+- Make consumers idempotent
+- Use dead letter queues for failed messages
+- Monitor queue depths and consumer lag
+- Design for eventual consistency
+- Version your message schemas
+- Include metadata (timestamp, correlationId, causationId)

package/data/architecture/event-driven/patterns.md

@@ -0,0 +1,129 @@
+# Event-Driven Architecture
+
+## Event Sourcing
+
+Store state as a sequence of events.
+
+```typescript
+interface Event {
+  id: string;
+  aggregateId: string;
+  type: string;
+  data: unknown;
+  timestamp: Date;
+  version: number;
+}
+
+class Account {
+  private balance = 0;
+  private version = 0;
+
+  static fromEvents(events: Event[]): Account {
+    const account = new Account();
+    events.forEach(event => account.apply(event));
+    return account;
+  }
+
+  private apply(event: Event): void {
+    switch (event.type) {
+      case 'MoneyDeposited':
+        this.balance += (event.data as { amount: number }).amount;
+        break;
+      case 'MoneyWithdrawn':
+        this.balance -= (event.data as { amount: number }).amount;
+        break;
+    }
+    this.version = event.version;
+  }
+}
+```
+
+## CQRS (Command Query Responsibility Segregation)
+
+Separate read and write models.
+
+```typescript
+// Write Model (Commands)
+class OrderCommandHandler {
+  async handle(cmd: PlaceOrderCommand): Promise<void> {
+    const order = new Order(cmd.orderId, cmd.items);
+    await this.eventStore.save(order.changes());
+  }
+}
+
+// Read Model (Queries)
+class OrderQueryService {
+  async getOrderSummary(orderId: string): Promise<OrderSummaryDTO> {
+    return this.readDb.query('SELECT * FROM order_summaries WHERE id = $1', [orderId]);
+  }
+}
+
+// Projection updates read model from events
+class OrderProjection {
+  async handle(event: OrderPlaced): Promise<void> {
+    await this.readDb.insert('order_summaries', {
+      id: event.orderId,
+      status: 'placed',
+      total: event.total
+    });
+  }
+}
+```
+
+## Saga Pattern
+
+Manage long-running transactions across services.
+
+```typescript
+class OrderSaga {
+  async execute(orderId: string): Promise<void> {
+    try {
+      await this.paymentService.charge(orderId);
+      await this.inventoryService.reserve(orderId);
+      await this.shippingService.schedule(orderId);
+    } catch (error) {
+      await this.compensate(orderId, error);
+    }
+  }
+
+  private async compensate(orderId: string, error: Error): Promise<void> {
+    await this.shippingService.cancel(orderId);
+    await this.inventoryService.release(orderId);
+    await this.paymentService.refund(orderId);
+  }
+}
+```
+
+## Event Versioning
+
+Handle schema changes gracefully.
+
+```typescript
+interface EventUpgrader {
+  upgrade(event: Event): Event;
+}
+
+class OrderPlacedV1ToV2 implements EventUpgrader {
+  upgrade(event: Event): Event {
+    const oldData = event.data as OrderPlacedV1Data;
+    return {
+      ...event,
+      type: 'OrderPlaced',
+      version: 2,
+      data: {
+        ...oldData,
+        currency: 'USD' // New field with default
+      }
+    };
+  }
+}
+```
+
+## Best Practices
+
+- Events are immutable facts
+- Include enough context in events for consumers
+- Version events from the start
+- Use idempotent event handlers
+- Design for eventual consistency
+- Consider snapshots for aggregates with many events

package/data/architecture/feature-toggles/index.md

@@ -0,0 +1,7 @@
+# Feature Toggles
+
+This directory contains feature toggle patterns.
+
+## Available Chunks
+
+- **patterns.md** - Release toggles, experiment toggles, ops toggles

package/data/architecture/feature-toggles/patterns.md

@@ -0,0 +1,73 @@
+# Feature Toggles
+
+## Toggle Types
+
+### Release Toggles
+Hide incomplete features in production.
+
+```typescript
+if (featureFlags.isEnabled('new-checkout')) {
+  return <NewCheckout />;
+}
+return <LegacyCheckout />;
+```
+
+### Experiment Toggles
+A/B testing and gradual rollouts.
+
+```typescript
+const variant = featureFlags.getVariant('pricing-experiment', userId);
+if (variant === 'new-pricing') {
+  return calculateNewPricing(cart);
+}
+return calculateLegacyPricing(cart);
+```
+
+### Ops Toggles
+Runtime operational control.
+
+```typescript
+if (featureFlags.isEnabled('enable-caching')) {
+  return cache.get(key) || fetchFromDatabase(key);
+}
+return fetchFromDatabase(key);
+```
+
+## Implementation
+
+```typescript
+interface FeatureFlags {
+  isEnabled(flag: string, context?: Context): boolean;
+  getVariant(flag: string, userId: string): string;
+}
+
+class FeatureFlagService implements FeatureFlags {
+  constructor(private config: Map<string, FlagConfig>) {}
+
+  isEnabled(flag: string, context?: Context): boolean {
+    const config = this.config.get(flag);
+    if (!config) return false;
+
+    if (config.percentage) {
+      return this.isInPercentage(context?.userId, config.percentage);
+    }
+
+    return config.enabled;
+  }
+
+  private isInPercentage(userId: string | undefined, percentage: number): boolean {
+    if (!userId) return false;
+    const hash = this.hashUserId(userId);
+    return (hash % 100) < percentage;
+  }
+}
+```
+
+## Best Practices
+
+- Remove toggles after feature is stable
+- Use clear naming conventions
+- Log toggle decisions for debugging
+- Test both toggle states
+- Limit number of active toggles
+- Document toggle purpose and expiration

package/data/architecture/gui/index.md

@@ -0,0 +1,7 @@
+# GUI Architecture Patterns
+
+This directory contains GUI architecture patterns.
+
+## Available Chunks
+
+- **patterns.md** - MVC, MVP, MVVM, Component Architecture

package/data/architecture/gui/patterns.md

@@ -0,0 +1,132 @@
+# GUI Architecture Patterns
+
+## MVC (Model-View-Controller)
+
+```typescript
+// Model - data and business logic
+class UserModel {
+  private users: User[] = [];
+
+  getUsers(): User[] { return this.users; }
+  addUser(user: User): void { this.users.push(user); }
+}
+
+// View - presentation
+class UserView {
+  render(users: User[]): void {
+    console.log('Users:', users);
+  }
+}
+
+// Controller - handles input, coordinates
+class UserController {
+  constructor(
+    private model: UserModel,
+    private view: UserView
+  ) {}
+
+  handleAddUser(userData: UserData): void {
+    const user = new User(userData);
+    this.model.addUser(user);
+    this.view.render(this.model.getUsers());
+  }
+}
+```
+
+## MVP (Model-View-Presenter)
+
+```typescript
+// View interface - defines what presenter can call
+interface UserView {
+  showUsers(users: User[]): void;
+  showError(message: string): void;
+}
+
+// Presenter - all presentation logic
+class UserPresenter {
+  constructor(
+    private view: UserView,
+    private model: UserModel
+  ) {}
+
+  loadUsers(): void {
+    try {
+      const users = this.model.getUsers();
+      this.view.showUsers(users);
+    } catch (error) {
+      this.view.showError('Failed to load users');
+    }
+  }
+}
+
+// View implementation - passive, no logic
+class UserListView implements UserView {
+  showUsers(users: User[]): void { /* render list */ }
+  showError(message: string): void { /* show error */ }
+}
+```
+
+## MVVM (Model-View-ViewModel)
+
+```typescript
+// ViewModel - exposes observable state
+class UserViewModel {
+  users = observable<User[]>([]);
+  isLoading = observable(false);
+
+  async loadUsers(): Promise<void> {
+    this.isLoading.set(true);
+    const users = await this.userService.getUsers();
+    this.users.set(users);
+    this.isLoading.set(false);
+  }
+}
+
+// View binds to ViewModel
+const UserList = observer(({ viewModel }: { viewModel: UserViewModel }) => (
+  <div>
+    {viewModel.isLoading.get() ? (
+      <Spinner />
+    ) : (
+      viewModel.users.get().map(user => <UserItem key={user.id} user={user} />)
+    )}
+  </div>
+));
+```
+
+## Component Architecture (React/Vue)
+
+```typescript
+// Presentational component - no state, just props
+const UserCard = ({ user, onDelete }: UserCardProps) => (
+  <div className="user-card">
+    <h3>{user.name}</h3>
+    <button onClick={() => onDelete(user.id)}>Delete</button>
+  </div>
+);
+
+// Container component - manages state
+const UserListContainer = () => {
+  const [users, setUsers] = useState<User[]>([]);
+
+  useEffect(() => {
+    userService.getUsers().then(setUsers);
+  }, []);
+
+  const handleDelete = (id: string) => {
+    userService.deleteUser(id).then(() => {
+      setUsers(users.filter(u => u.id !== id));
+    });
+  };
+
+  return <UserList users={users} onDelete={handleDelete} />;
+};
+```
+
+## Best Practices
+
+- Separate UI logic from business logic
+- Keep views as simple as possible
+- Use unidirectional data flow when possible
+- Make components reusable and testable
+- Choose pattern based on framework and team familiarity