Review persistence architecture

This guide describes the recommended architecture for collaborative review workflows where multiple users comment, annotate, and return to documents across sessions and devices.

Recommendation summary:

  • Internal persistence/sync format — Instant JSON
  • External interoperability format — XFDF
  • Collaboration backbone — Document Engine with Instant synchronization

Canonical architecture

For collaborative review, use Document Engine as the source of truth and Instant synchronization for multiuser updates.

  1. Clients load documents from Document Engine.
  2. Users create/edit annotations in Web SDK.
  3. Changes are persisted server-side and synchronized to other clients through Instant.
  4. Clients reconnect and resume from server state across sessions/devices.
  5. If needed, export to XFDF for external systems.
  • Single source of truth on the server — Treat server-backed document state as authoritative for team workflows.
  • Use Instant JSON internally — Prefer Instant JSON for compact, implementation-friendly persistence and synchronization payloads.
  • Use XFDF at boundaries — Export/import XFDF when integrating with Adobe Acrobat or other XFDF-compatible tools.
  • Keep autosave and sync explicit in UX — Surface save/sync status in review-heavy applications.
  • Define conflict semantics early — For concurrent edits, use Instant synchronization to avoid building ad hoc conflict logic.

Storage and sync flow (reference) 

Reviewer A/B opens document -> Document Engine returns current annotation state
Reviewer A annotates -> change persisted server-side (Instant JSON-based)
Instant sync broadcasts change -> Reviewer B receives update
Reviewer B reconnects later -> same server-backed state restored
Optional integration export -> XFDF generated for external system

Anti-patterns

  • Local-only persistence for collaborative workflows — Leads to lost updates and poor multidevice continuity.
  • Using XFDF as the primary real-time sync format — XFDF is excellent for interoperability, but not ideal as the internal collaborative sync backbone.
  • Assuming single-user storage patterns will scale to team review — Multiuser sessions need explicit server-backed synchronization.