Collaboration - Brainbox

Brainbox is built on a local-first architecture that enables real-time collaboration, offline editing, and automatic conflict resolution using CRDTs (Conflict-free Replicated Data Types).

How It Works

Brainbox’s collaboration system operates on four core principles:

Local-first storage

Every client maintains a full SQLite database. All changes write locally first, ensuring instant responsiveness and offline capability.

Background sync

When connected, changes automatically sync to the server via WebSocket. The server persists data to PostgreSQL as the source of truth.

CRDT merge

Concurrent edits from multiple users merge automatically using Yjs CRDTs. No manual conflict resolution required.

Real-time updates

All connected clients receive live updates through WebSocket broadcasts, showing changes as they happen.

Architecture Overview

The sync architecture consists of multiple layers:

┌─────────────────────────────────────────────────────────┐
│                    Client (Browser)                      │
├─────────────────────────────────────────────────────────┤
│  UI Components (React)                                   │
│  ↓                                                       │
│  Client Database (SQLite - WASM)                         │
│  ↓                                                       │
│  Sync Engine (@brainbox/client)                         │
│  ↓                                                       │
│  WebSocket Connection                                    │
└─────────────────────────────────────────────────────────┘
                        ↕
┌─────────────────────────────────────────────────────────┐
│                    Server (Node.js)                      │
├─────────────────────────────────────────────────────────┤
│  WebSocket Handlers (Fastify)                           │
│  ↓                                                       │
│  Synchronizers (Broadcasters)                           │
│  ↓                                                       │
│  Server Database (PostgreSQL)                            │
│  ↓                                                       │
│  CRDT Engine (Yjs)                                      │
└─────────────────────────────────────────────────────────┘

Synchronization Types

Brainbox syncs different types of data through specialized synchronizers:

Node Updates

Changes to node attributes (name, fields, etc.)

Document Updates

Rich text content changes in pages and records

Collaborations

User presence and active collaborators

Node Reactions

Emoji reactions on messages

Node Interactions

User interactions and activity

Node Tombstones

Deleted nodes and cleanup

User Updates

User profile and settings changes

Real-Time Editing

Multiple users can edit the same document simultaneously without conflicts:

Presence Awareness

See who else is viewing or editing:

Active users - Avatar indicators show who’s in the document
Live cursors - See where others are typing in real-time
Selections - View other users’ text selections
Activity status - Online/offline indicators

CRDT-Based Merging

Brainbox uses Yjs for conflict-free collaborative editing:

How CRDTs Work
Rich Text Handling
Database Merging

CRDTs (Conflict-free Replicated Data Types) are data structures that can be updated independently on multiple replicas and automatically merged:Key properties:

Commutative - Order of operations doesn’t matter
Associative - Grouping of operations doesn’t matter
Idempotent - Applying an operation twice has the same effect as once

Example:

// User A inserts "Hello" at position 0
// User B inserts "World" at position 0
// Traditional merge: conflict!
// CRDT merge: "HelloWorld" or "WorldHello" (deterministic)

// With Yjs:
import * as Y from 'yjs'

const doc = new Y.Doc()
const yText = doc.getText('content')

// User A's edit
yText.insert(0, 'Hello')

// User B's edit (concurrent)
yText.insert(0, 'World')

// Result: Automatic merge with preserved intent

Yjs handles rich text with formatting marks:

Character-level tracking - Each character has a unique ID
Format preservation - Bold, italic, etc. merge correctly
Block structure - Headings, lists, and blocks maintain integrity
Deletion tracking - Tombstones prevent resurrection of deleted content

Under the hood:

// Brainbox page content structure
{
  type: "rich_text",
  blocks: {
    "block_1": {
      id: "block_1",
      type: "paragraph",
      content: [
        {
          type: "text",
          text: "Collaborative editing",
          marks: [
            { type: "bold", attrs: {} }
          ]
        }
      ],
      index: "a0",
      parentId: null
    }
  }
}

Database fields and records also use CRDTs:

Field values - Last-write-wins with vector clocks
Field definitions - Schema changes merge safely
Record order - Fractional indexing maintains sort order
Views - Filter and sort configurations sync independently

Conflict resolution:

Scenario	Resolution
Same field edited by two users	Last write wins (by timestamp)
Different fields edited	Both changes apply
Record created with same ID	Server-assigned ID prevents collision
View filters changed	Per-user view state (not synced)

Offline Mode

Brainbox works fully offline with automatic sync when reconnected:

Offline Capabilities

Full CRUD

Create, read, update, and delete nodes offline

File Uploads

Queue file uploads for processing when online

Search

Search locally cached content

Optimistic UI

Changes appear instantly in the UI

Offline Workflow

Connection lost

WebSocket disconnects. UI shows offline indicator.

Continue working

All changes write to local SQLite database. No interruption to user experience.

Queue sync

Changes queue with pending sync status.

Reconnect

WebSocket reconnects automatically when internet returns.

Sync queued changes

Pending changes upload to server in order.

Merge conflicts

CRDTs merge any concurrent changes from other users.

Broadcast updates

Server broadcasts merged state to all clients.

Handling Conflicts

In most cases, conflicts resolve automatically via CRDTs. Manual intervention is rarely needed.

When conflicts do occur:

Automatic Resolution
Edge Cases

Most conflicts resolve without user action:Text edits:

Concurrent insertions: Both apply, merged by CRDT
Concurrent deletions: Deleted content removed
Format conflicts: Both formats apply (text can be bold AND italic)

Database edits:

Different fields: Both changes apply
Same field: Last write wins (by timestamp)
Record deletion: Tombstone propagates, record removed for all users

Sync Engine Implementation

The sync engine coordinates data flow between client and server:

Client-Side Handlers

Located in packages/client/src/handlers/:

// Example: Node updates handler
export async function handleNodeUpdates(
  input: NodesUpdatesInput
): Promise<void> {
  const db = await openDatabase();
  
  for (const node of input.data) {
    await db
      .insertInto('nodes')
      .values({
        id: node.id,
        type: node.type,
        attributes: JSON.stringify(node.attributes),
        updatedAt: node.updatedAt,
      })
      .onConflict((oc) =>
        oc.column('id').doUpdateSet({
          attributes: JSON.stringify(node.attributes),
          updatedAt: node.updatedAt,
        })
      )
      .execute();
  }
}

Server-Side Broadcasters

Located in apps/server/src/synchronizers/:

// Example: Broadcasting node updates
export async function broadcastNodeUpdate(
  nodeId: string,
  workspaceId: string
): Promise<void> {
  const node = await getNode(nodeId);
  
  await broadcastToWorkspace(workspaceId, {
    type: 'nodes-updates',
    data: [node],
  });
}

Performance Optimization

Brainbox optimizes sync performance through:

Batching

Multiple changes batch into single sync messages

Debouncing

Rapid edits debounce before syncing

Compression

WebSocket messages use compression

Delta Sync

Only changes sync, not full documents

Indexing

SQLite indexes speed up queries

Connection Pooling

Reuse database connections

Sync Strategies

Immediate Sync
Debounced Sync
Batched Sync

High-priority changes sync immediately:

Chat messages
Node creation/deletion
Permission changes
User presence updates

Data Consistency

Brainbox ensures data consistency across clients:

Consistency Guarantees

Eventual Consistency

All clients eventually converge to the same state:

Guarantee: Given no new updates, all replicas converge
Timeline: Typically within seconds of reconnection
Verification: Vector clocks track causal ordering

Causal Consistency

Operations preserve cause-and-effect relationships:

Guarantee: If operation A causes operation B, all clients see A before B
Implementation: Logical timestamps and dependency tracking
Example: Reply to message always appears after original message

Strong Consistency (Server)

Server database maintains strong consistency:

Guarantee: Server always has authoritative state
Implementation: PostgreSQL ACID transactions
Use: Conflict resolution and audit trail

Conflict-Free Operations

Certain operations are guaranteed conflict-free:

Operation	Conflict-Free?	Reason
Insert text	✓	CRDT positions are unique
Delete text	✓	Tombstones prevent resurrection
Create node	✓	UUIDs prevent ID collision
Update different fields	✓	Independent field state
Add reaction	✓	Set-based CRDT
Update same field	✗	Last-write-wins
Reorder items	~	Fractional indexing reduces conflicts

Scaling Collaboration

Brainbox scales to support large teams:

WebSocket Rooms

Users join workspace-specific rooms for targeted broadcasts

Redis Pub/Sub

Horizontal scaling across multiple server instances

Connection Pooling

Efficient database connection management

Rate Limiting

Prevent abuse with per-user rate limits

Best Practices

Trust the sync engine

Don’t manually refresh to see changes. The sync engine automatically propagates updates in real-time.

Work offline confidently

Brainbox is designed for offline work. Don’t wait for internet connection - keep working and changes will sync later.

Avoid rapid field type changes

Changing field types (e.g., text to number) can cause data loss if users have offline edits. Plan schema changes carefully.

Monitor sync status

Watch the sync indicator in the UI. If changes aren’t syncing, check your connection.

Troubleshooting

Sync Issues
Conflict Issues
Offline Issues

Changes not syncing:

Check internet connection
Verify WebSocket status in network tab
Check browser console for errors
Try disconnecting and reconnecting
Clear local cache and re-sync

Slow sync:

Check network speed
Reduce concurrent edits
Limit file upload size
Check server load

Technical Deep Dive

For developers interested in the implementation:

CRDT Package

packages/crdt/ - Yjs document handling

Client Sync

packages/client/ - Sync engine and handlers

Server Sync

apps/server/src/synchronizers/ - Broadcasters

WebSocket API

apps/server/src/api/ - WebSocket routes

Next Steps

Pages

Real-time collaborative editing

Databases

Collaborative data management

Chat

Real-time messaging

Development

Build with Brainbox

Get Started

Core Features

Self-Hosting

Architecture

​How It Works

​Architecture Overview

​Synchronization Types

Node Updates

Document Updates

Collaborations

Node Reactions

Node Interactions

Node Tombstones

User Updates

​Real-Time Editing

​Presence Awareness

​CRDT-Based Merging

​Offline Mode

​Offline Capabilities

Full CRUD

File Uploads

Search

Optimistic UI

​Offline Workflow

​Handling Conflicts

​Sync Engine Implementation

​Client-Side Handlers

​Server-Side Broadcasters

​Performance Optimization

Batching

Debouncing

Compression

Delta Sync

Indexing

Connection Pooling

​Sync Strategies

​Data Consistency

​Consistency Guarantees

​Conflict-Free Operations

​Scaling Collaboration

WebSocket Rooms

Redis Pub/Sub

Connection Pooling

Rate Limiting

​Best Practices

​Troubleshooting

​Technical Deep Dive

CRDT Package

Client Sync

Server Sync

WebSocket API

​Next Steps

Pages

Databases

Chat

Development

Build docs developers (and LLMs) love

How It Works

Architecture Overview

Synchronization Types

Real-Time Editing

Presence Awareness

CRDT-Based Merging

Offline Mode

Offline Capabilities

Offline Workflow

Handling Conflicts

Sync Engine Implementation

Client-Side Handlers

Server-Side Broadcasters

Performance Optimization

Sync Strategies

Data Consistency

Consistency Guarantees

Conflict-Free Operations

Scaling Collaboration

Best Practices

Troubleshooting

Technical Deep Dive

Next Steps