EventLogStorage Interface

EventLogStorage handles the append-only event log and board snapshots used by the collaboration service.

abstract class EventLogStorage {
    abstract append(event: Omit<BoardEvent, 'id'>): Promise<BoardEvent>;
    abstract appendBatch(events: Omit<BoardEvent, 'id'>[]): Promise<BoardEvent[]>;
    abstract getEvents(boardId: string, afterSequence?: number): Promise<BoardEvent[]>;
    abstract getLatestSequence(boardId: string): Promise<number>;
    abstract createSnapshot(
        boardId: string,
        data: Record<string, unknown>,
        eventSequence: number,
    ): Promise<BoardSnapshot>;
    abstract getLatestSnapshot(boardId: string): Promise<BoardSnapshot | null>;
}

BoardEvent

interface BoardEvent {
    id: string;
    boardId: string;
    pageId?: string;
    type: BoardEventType;
    payload: Record<string, unknown>;
    userId: string;
    sequence: number;
    timestamp: string;
}

type BoardEventType =
    | 'elementCreated'
    | 'elementUpdated'
    | 'elementDeleted'
    | 'pageAdded'
    | 'pageRemoved'
    | 'pageReordered'
    | 'boardUpdated';

BoardSnapshot

interface BoardSnapshot {
    id: string;
    boardId: string;
    snapshotData: Record<string, unknown>;
    eventSequence: number;
    createdAt: string;
}

Methods

append

Appends a single event to the log. The implementation should assign a unique id.

appendBatch

Appends multiple events atomically.

getEvents

Returns all events for a board. Optionally filters to events after a given sequence number (used for delta sync).

getLatestSequence

Returns the highest sequence number for a board, or 0 if no events exist.

createSnapshot

Creates a point-in-time snapshot of a board's data. Used when persistent sessions are archived.

getLatestSnapshot

Returns the most recent snapshot for a board, or null if none exists.

How Events Are Used

The CollaborationService writes events for every mutation:

Element creates → elementCreated
Element updates → elementUpdated
Element deletes → elementDeleted
Page operations → pageAdded, pageRemoved, pageReordered
Board changes → boardUpdated

The event log is also used for delta sync during reconnection: if a client disconnects and reconnects, the server can send only the missed events (up to 1000) rather than a full board sync.

EventLogStorage Interface

On this page