CRDT Offline Collaboration

Overview#

The CRDT Offline Collaboration module enables real-time document collaboration that continues to function in disconnected, degraded, intermittent, and limited-bandwidth (DDIL) environments. Built on Y.js Conflict-Free Replicated Data Types (CRDTs), the system allows multiple operators to edit shared documents simultaneously. When network connectivity is lost, operators continue working on their local copy; on reconnection, all changes merge automatically without conflicts, data loss, or manual resolution. Document state is persisted to PostgreSQL-backed snapshots, ensuring durability across sessions.

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 CRDT mathematical guarantees ensure that all participants converge to the same document state regardless of the order in which edits are received.

• Conflict-Free Merging on Reconnection - When an operator works offline and later reconnects, their accumulated edits merge automatically with changes made by other operators during the disconnection period. No manual conflict resolution is required -- the CRDT algorithm produces a deterministic merged result that preserves all participants' 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 state 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. The system tolerates extended disconnection periods (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 and supporting 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; 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 that feeds 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.

GraphQL:

crdtDocuments

documentSnapshots

documentParticipants

createCrdtDocument

updateDocumentSnapshot

syncDocumentState

Last Reviewed: 2026-04-02