Archetype 17 — Shared Mutable Subject #
What this archetype is #
Many users edit one live shared object. Correctness depends on ordered operations and convergent state.
Examples: collaborative docs, whiteboards, multiplayer editors.
We will use shared document editing as the running example.
Layer 1: Entities and Postgres table design #
OperationLog
SubjectState
VersionState
SnapshotState
create table documents (
document_id uuid primary key,
subject_state jsonb not null,
version bigint not null default 1,
updated_at timestamptz not null default now()
);
create table document_ops (
document_id uuid not null references documents(document_id),
version bigint not null,
author_id bigint not null,
op jsonb not null,
created_at timestamptz not null default now(),
primary key (document_id, version)
);
create table document_snapshots (
document_id uuid not null references documents(document_id),
snapshot_version bigint not null,
snapshot_state jsonb not null,
created_at timestamptz not null default now(),
primary key (document_id, snapshot_version)
);
Layer 2: Write path mechanics #
Apply operation with version gate #
begin;
update documents
set subject_state = $3,
version = version + 1,
updated_at = now()
where document_id = $1
and version = $2;
insert into document_ops (
document_id, version, author_id, op
) values (
$1, $2 + 1, $4, $5
);
commit;
This is the centralized sequencer model in SQL form.
Layer 3: Fault tolerance #
- lost concurrent edit
- duplicate op
- out-of-order apply
- divergence
- stale coordinator snapshot
Layer 4: Scale #
Default hotspots:
- hot-subject coordinator
- high per-subject op rate
- replay cost
- subscriber fanout
Common mitigations:
- one coordinator per document
- periodic snapshots
- op log truncation after snapshot