Architecture

​

Overview

​

Core Principles

​

Architecture Components

​

1. Event Store

interface KSyncEvent<T = unknown> {
  id: string;           // Unique event identifier
  type: string;         // Event type (e.g., 'message', 'user-joined')
  data: T;              // Event payload (validated by schema)
  timestamp: number;    // When the event occurred
  clientId: string;     // Which client created the event
  version: number;      // Event sequence number
}

• Immutable: Events are never modified once created
• Ordered: Events have sequence numbers for consistent ordering
• Typed: Each event type has a corresponding Zod schema
• Traceable: Full audit trail of all changes

​

2. Storage Layer

import { IndexedDBStorage } from '@klastra/ksync';

const storage = new IndexedDBStorage();
// Automatically persists events to browser's IndexedDB

import { MemoryStorage } from '@klastra/ksync';

const storage = new MemoryStorage();
// Fast in-memory storage for servers or testing

class CustomStorage implements KSyncStorage {
  async storeEvent(event: KSyncEvent): Promise<void> {
    // Your custom storage logic
  }
  
  async getEvents(): Promise<KSyncEvent[]> {
    // Your custom retrieval logic
  }
}

​

3. Synchronization Layer

• Automatic Reconnection: Handles network interruptions gracefully
• Event Batching: Groups events for efficient network usage
• Conflict Resolution: Last-write-wins with timestamp ordering
• Heartbeat Monitoring: Detects and handles stale connections

​

4. Tab Coordination

// Automatic leader election using Web Locks
navigator.locks.request('ksync-leader', () => {
  // This tab is now the leader
  // Only the leader maintains WebSocket connection
});

// Fallback using IndexedDB for coordination
// Uses timestamps and heartbeats for leader election

• Single Connection: Only one tab per origin connects to the server
• Efficient: Reduces server load and network usage
• Reliable: Automatic failover if leader tab closes

​

5. State Materialization

// Events → State transformation
ksync.defineMaterializer('chat', (events: KSyncEvent[]) => {
  const state = {
    messages: [],
    users: new Set(),
    typingUsers: new Set(),
  };

  for (const event of events) {
    switch (event.type) {
      case 'message':
        state.messages.push(event.data);
        break;
      case 'user-joined':
        state.users.add(event.data.username);
        break;
      case 'typing-start':
        state.typingUsers.add(event.data.username);
        break;
      case 'typing-stop':
        state.typingUsers.delete(event.data.username);
        break;
    }
  }

  return state;
});

​

Data Flow

​

Step-by-Step Flow

1. User Action: User performs an action (e.g., sends a message)
2. Event Creation: kSync creates a typed event with schema validation
3. Local Storage: Event is immediately stored locally
4. Optimistic Update: UI updates immediately for responsive UX
5. Network Sync: Event is sent to server via WebSocket
6. Server Broadcast: Server broadcasts event to all connected clients
7. Remote Application: Other clients receive and apply the event
8. State Materialization: Events are transformed into queryable state

​

Performance Optimizations

​

Event Batching

// Events are batched for 50ms before sending
const config = {
  eventBatchSize: 10,        // Max events per batch
  batchTimeout: 50,          // Max wait time (ms)
};

​

Memory Management

• Event Trimming: Automatically removes old events to prevent memory leaks
• Lazy Loading: Only loads events when needed
• Efficient Indexing: Uses optimized data structures for fast queries

​

Network Efficiency

• Connection Pooling: Reuses WebSocket connections
• Compression: Automatically compresses large payloads
• Heartbeat: Minimal ping/pong for connection health

​

Conflict Resolution

​

Last-Write-Wins (LWW)

// Events are ordered by timestamp
const resolveConflict = (eventA: KSyncEvent, eventB: KSyncEvent) => {
  return eventA.timestamp > eventB.timestamp ? eventA : eventB;
};

​

Custom Resolution

ksync.defineMaterializer('document', (events) => {
  // Custom conflict resolution logic
  const conflictingEvents = events.filter(/* conflict detection */);
  const resolved = customResolve(conflictingEvents);
  return applyResolution(resolved);
});

​

Security Considerations

// Invalid events are rejected
await ksync.send('message', {
  content: 123, // ❌ Should be string
}); // Throws validation error

const ksync = createKSync({
  serverUrl: 'ws://localhost:8080',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

ksync.defineSchema('message', z.object({
  content: z.string().max(1000), // Limit message length
  author: z.string().regex(/^[a-zA-Z0-9_]+$/), // Alphanumeric only
}));

​

Scalability

​

Horizontal Scaling

​

Vertical Scaling

• Event Partitioning: Split events by type or user
• Sharding: Distribute events across multiple storage instances
• Caching: Use Redis for frequently accessed events

​

Comparison with Other Architectures

​

Next Steps