CRDT Offline Collaboration

Overview#

A forward operating base loses its satellite link at 02:00 during an active operation. Three staff officers are mid-draft on the same operations order. Under a traditional system, the disconnection freezes progress and risks conflicting versions on reconnection. With CRDT Offline Collaboration, each officer continues editing their section locally; when the link restores ninety minutes later, all three documents merge automatically without a single conflict or lost paragraph.

Built on Y.js Conflict-Free Replicated Data Types, the module provides real-time collaborative editing that continues working in disconnected, degraded, intermittent, and limited-bandwidth (DDIL) environments. Defence organisations, emergency management agencies, and maritime operators all face connectivity gaps that traditional collaboration tools cannot survive. This module is designed specifically for those conditions, with PostgreSQL-backed snapshots ensuring document durability across the full session lifecycle.

Key Features#

• Y.js CRDT Real-Time Collaboration: Shared documents use Y.js CRDT data structures that support concurrent editing by multiple operators. Changes propagate to all connected participants in real time via WebSocket connections. The mathematical guarantees of CRDTs ensure that all participants converge to the same document state regardless of the order in which edits arrive.

• Conflict-Free Merging on Reconnection: When an operator works offline and later reconnects, their accumulated edits merge automatically with changes made by others during the disconnection. No manual conflict resolution is required; the CRDT algorithm produces a deterministic result that preserves every participant's contributions.

• PostgreSQL-Backed Snapshot Persistence: Document state is periodically snapshotted to PostgreSQL, providing durable storage that survives server restarts and enables document recovery. Snapshots capture the full CRDT state, allowing new participants to load the current document efficiently without replaying the entire edit history.

• DDIL Environment Support: The architecture is designed for tactical edge deployments where network connectivity is unreliable. Operators at forward positions can edit operational documents (orders, reports, briefings) offline with confidence that their work will merge cleanly when connectivity is restored, tolerating extended disconnection periods from hours to days without data loss.

• Awareness Protocol: The Y.js awareness protocol tracks each participant's cursor position, selection state, and user identity in real time. Connected operators see where their collaborators are working within the document, preventing editing collisions during coordinated authoring. Awareness state is ephemeral and does not persist to the database.

Use Cases#

• Collaborative Operations Orders: Multiple staff officers draft and refine operations orders simultaneously, with each section owner working on their portion while seeing real-time updates from colleagues.
• Forward Operating Base Reporting: Operators at disconnected forward positions draft situation reports offline; those reports merge with headquarters-edited versions on reconnection without overwriting either party's contributions.
• Intelligence Assessment Authoring: Analysts collaboratively develop intelligence assessments with real-time visibility into each other's additions and edits, maintaining a single authoritative document.
• After-Action Review Documentation: Teams at different locations contribute to shared after-action review documents, with CRDT merging ensuring no contributions are lost even with intermittent connectivity.

Integration#

• Briefing Intelligence: CRDT-enabled documents serve as the authoring layer for briefing content feeding into the briefing pipeline.
• Satellite Mesh Communications: Document synchronisation traffic routes through the satellite mesh when primary connectivity is unavailable.
• Unified Operational Events: Document creation and significant edits generate events in the unified timeline for audit purposes.
• Organisation Scoping: All documents are scoped to the owning organisation with access controls enforced at the document level and organization_id included in every query.

Current GraphQL surface uses pendingOperations (query) and syncOperations (mutation) for offline operation transport. Collaboration state is exposed through the Collaboration domain's note, task, mention, activity, and lock APIs.

Open Standards#

• Y.js CRDT (Conflict-Free Replicated Data Types): The module is built on Y.js, which implements the YATA (Yet Another Transformation Approach) sequence CRDT algorithm, providing mathematically guaranteed convergence so that all participants reach an identical document state regardless of edit order or offline duration.
• RFC 6455 (WebSocket Protocol): Real-time document updates and the Y.js awareness protocol are transported over persistent WebSocket connections, enabling low-latency bidirectional sync when connectivity is available.
• GraphQL: Offline operation transport is exposed through a GraphQL API surface; the pendingOperations query retrieves queued edits from PostgreSQL and the syncOperations mutation persists and reconciles them on reconnection.
• W3C Web Storage (localStorage): The client-side operation queue, version vector, and node identity are durably persisted to the browser's localStorage API so accumulated offline edits survive page reloads and extended disconnection periods.
• ISO 8601: All operation timestamps (createdAt, syncedAt, lastSyncAttempt, lastSuccessfulSync) are serialised as ISO 8601 strings via toISOString(), providing unambiguous causality ordering across distributed nodes.
• W3C WCAG 2.2: The collaboration presence layer explicitly targets WCAG 2.2 AAA conformance, using ARIA live regions to announce collaborator join and leave events to screen readers and ensuring all cursor and selection indicators meet contrast ratio requirements.
• JSON (ECMA-404 / RFC 8259): WebSocket message framing between client and server uses JSON-encoded payloads for Y.js update envelopes, awareness state, and control messages (ping/pong), and the offline operation queue is persisted as JSON in local storage.

Last Reviewed: 2026-04-02 Last Updated: 2026-04-14