System Design

1. Observer Pattern

What is it? The Observer pattern is like a subscription system - components can subscribe to events and get notified when those events occur.

How we use it: In our system, this pattern enables real-time communication between different parts of the application. For example, when a user speaks, multiple components need to know about it:

• • The Speech-to-Text service needs to process the audio
• • The virtual agent needs to show listening indicators
• • The UI needs to update its state

Benefits:

• • Components don't need to know about each other directly
• • Easy to add new features without changing existing code
• • Enables real-time updates across the system

The Observer pattern showing how events flow through the system

2. Template Method Pattern

What is it? Think of this pattern like a cooking recipe with some steps that must be followed exactly and others that can be customized. It defines a skeleton of operations while allowing some steps to be overridden.

How we use it: Our ApplicationController provides a standard way to initialize and run services while allowing each service to define its own specific behavior:

• • Every service follows the same lifecycle (initialize → configure → start)
• • Each service can customize how it handles these steps
• • Ensures consistent behavior across different services

The Template Method pattern showing standard service lifecycle

3. Factory Pattern

What is it? The Factory pattern is like a specialized workshop that knows how to create different types of components. Instead of creating objects directly, we ask the factory to create them for us.

How we use it: When the ConversationalAgent needs different services (speech, text, etc.), it uses factories to create them:

• • Centralizes component creation logic
• • Makes it easy to switch between different implementations
• • Handles complex initialization requirements

The Factory pattern showing how components are created

4. Strategy Pattern

What is it? The Strategy pattern is like having interchangeable tools for the same job. It allows us to switch between different algorithms or approaches at runtime.

How we use it: Our AI services use this pattern to support different implementation strategies:

• • Speech-to-Text can switch between local and cloud processing
• • Text-to-Speech can use different voice synthesis methods
• • RAG service can use different embedding approaches

The Strategy pattern showing interchangeable service implementations

5. Mediator Pattern

What is it? Think of the Mediator pattern like an air traffic controller - instead of planes communicating directly with each other, they all communicate through the controller.

How we use it: Our NetworkScene acts as a mediator for all network communication:

• • Handles message routing between components
• • Manages peer connections and room state
• • Coordinates real-time updates

The Mediator pattern showing centralized communication control

How These Patterns Work Together

These patterns complement each other to create a robust and flexible system:

• • The Observer pattern enables event-driven communication
• • The Template Method ensures consistent service behavior
• • The Factory creates the right components when needed
• • The Strategy pattern allows for flexible implementations
• • The Mediator coordinates all these interactions

How different design patterns interact in our system

1. Repository Pattern

Purpose: Abstracts data persistence operations

Implementation: Collection class in db.ts

class Collection<T extends { _id?: string }> {
  private tableName: string;
  
  constructor(tableName: string) {
    this.tableName = tableName;
    this.ensureTableExists();
    this.ensureIndexes();
  }

  // CRUD Operations
  findOne(query: Partial<T>): T | null
  find(query: Partial<T> = {}): T[]
  insertOne(doc: T): { insertedId: string }
  updateOne(filter: Partial<T>, update: UpdateOptions): UpdateResult
  deleteOne(filter: Partial<T>): { deletedCount: number }
}

2. Singleton Pattern

Purpose: Ensures single database connection instance

Implementation: SQLite database connection in sqlite.ts

// Development mode singleton
if (process.env.NODE_ENV === "development") {
  let globalWithSqlite = global as typeof globalThis & {
    _sqliteDatabase?: BetterSqlite3.Database;
  };

  if (!globalWithSqlite._sqliteDatabase) {
    globalWithSqlite._sqliteDatabase = new BetterSqlite3(DB_PATH);
    initDatabase(globalWithSqlite._sqliteDatabase);
  }
  db = globalWithSqlite._sqliteDatabase;
}

3. Factory Pattern

Purpose: Creates database client instances

Implementation: getDbClient function in db.ts

export function getDbClient() {
  return {
    db: function(dbName: string) {
      return {
        collection: function<T extends { _id?: string }>(collectionName: string) {
          return new Collection<T>(collectionName);
        }
      };
    }
  };
}

4. Strategy Pattern

Purpose: Handles different types of database operations

Implementation: Relations class for handling relationships

export class Relations {
  static async linkDocumentToActivity(documentId: string, activityId: string): Promise<void>
  static async unlinkDocumentFromActivity(documentId: string, activityId: string): Promise<void>
  static getDocumentsByActivityId(activityId: string): string[]
  static getActivitiesByDocumentId(documentId: string): string[]
}

5. Adapter Pattern

Purpose: Adapts MongoDB-like operations to SQLite

Implementation: Collection class methods mimicking MongoDB operations

// MongoDB-like operations
updateOne(
  filter: Partial<T>,
  update: { 
    $set?: Partial<T>, 
    $addToSet?: Record<string, any>, 
    $pull?: Record<string, any> 
  }
): { matchedCount: number, modifiedCount: number }

Benefits of Used Patterns