Actors
- Product manager editing requirements
- Architect maintaining blueprints
- Reviewer approving or rejecting suggestions
- AI agent drafting or proposing a patch
- Commenter and mentioned teammate
- Org admin or auditor
LIVING SPECIFICATION / MOCK 04
Design structured Requirements and Blueprint documents where humans and agents coedit, comment, suggest, publish versions, and survive offline races without losing intent.
OPENING PROMPT
Read this once, then begin aloud. Spend the first two minutes establishing contract, actors, risk and what must remain authoritative.
Design LivingSpec, a multi-tenant collaborative editor for structured Requirements and Blueprints. Humans and AI agents edit concurrently; documents contain typed requirement blocks, acceptance criteria, architecture components and references. Users need presence, comments, suggestions, offline edits, version history, approval, diff and a stable published revision for downstream work orders.
Use convergent draft operations for availability, but make schema-valid publication a server-authoritative transaction. Draft collaboration and approved truth have intentionally different consistency models.
REQUIREMENTS
These are supplied mock numbers for sizing and follow-ups. Say your assumptions before using them.
HIGH-LEVEL DESIGN
Name the authoritative state, derived projections, asynchronous boundaries and the exact point where a business decision becomes durable.
STORAGE + ACCESS
The table is logical, not a mandate for one database. Choose physical stores after access patterns, transactions, retention and rebuildability are clear.
| Entity | Primary / unique key | Important fields and purpose |
|---|---|---|
| Document |
(tenant_id, document_id)
|
type, title, draft_epoch, published_revision, acl_epoch |
| Block |
(document_id, block_id)
|
kind, parent_id, rank, attributes, tombstone |
| Operation |
(document_id, draft_epoch, actor_id, op_seq)
|
client_op_id, causal_clock, payload, received_at |
| Snapshot |
(document_id, draft_epoch, snapshot_seq)
|
state_blob_hash, vector_clock, schema_version |
| Suggestion |
(document_id, suggestion_id)
|
base_clock, patch, author, state, decision_version |
| CommentThread |
(document_id, thread_id)
|
anchor_block, relative_range, context_hash, state |
| PublishedRevision |
(document_id, revision)
|
content_hash, approval_set, source_clock, immutable_body |
| ReferenceEdge |
(from_revision, from_block, to_document, to_block)
|
edge_type, resolution_state |
WS /v1/docs/{id}/sessions
Join with draft epoch, auth token and last vector clock
snapshot + missing opsPOST /v1/docs/{id}/operations
Batch offline ops; clientOpId dedupe
accepted clock / rejected epochPOST /v1/docs/{id}/suggestions
Patch against base clock with intent summary
201 {suggestionId,rebaseStatus}POST /v1/suggestions/{id}/decision
Accept/reject with expected decisionVersion
200 / 409POST /v1/docs/{id}/publish
Expected draft clock + approvals + idempotency key
201 {revision,contentHash}GET /v1/docs/{id}/diff?from=&to=
Semantic block diff between immutable revisions
200 {changes}00:00 → 30:00
Answers are written in a speakable first-person style. Turn on Practice Mode to hide them, answer aloud, then reveal one at a time.
Candidate · clear top-down answerI see two promises. Drafts should feel instant and keep working offline. Published versions must be fixed, reviewed, and safe for other systems to use. I would design those as separate paths.
Why this mattersThis gives the interviewer a map before any boxes appear, and it makes the system's most important trust decision explicit.
Candidate · clear top-down answerVersion one supports structured requirements, comments, suggestions, offline edits, and publishing a fixed revision. People may edit; agents may only suggest. We will not build free-form design tools or automatic code changes yet.
Why this mattersA narrow first release keeps the design realistic. It also shows which tempting features can wait without weakening the core product.
Candidate · clear top-down answerThe peak is 8,000 small edit operations each second, or about 2.8 MB/s. If that peak lasted all day, the raw edit log would be roughly 240 GB/day before copies and indexes. The bigger storage risk is keeping every keystroke forever. I would keep recent edits for fast replay, combine older ones into snapshots, and keep published versions permanently. The calculator deliberately shows the worst case so we can size retention safely.
Why this mattersThe calculation is not about perfect forecasting. It identifies the part most likely to run out of capacity or delay users.
Candidate · clear top-down answerThe main records are document, block, edit operation, snapshot, suggestion, comment, approval, and published revision. Blocks get stable IDs so comments and moves keep pointing to the right thing. We read a room by document ID and sequence, reconnect from a client's last sequence, and publish by exact snapshot hash. Presence and cursor positions are temporary and do not belong in the permanent truth.
Why this mattersA small set of records is easier to reason about. Exact versions keep later changes from silently rewriting an earlier decision.
Candidate · clear top-down answerA conflict-free replicated data type, or CRDT, is a merge method that lets offline edits meet later without losing either side. I would use it for draft text and ordering, but not for publishing, permissions, approvals, or billing.
Why this mattersThe merge tool solves concurrent draft edits, not business authority. Keeping publish and approval transactional prevents “it merged” from being mistaken for “it is valid.”
Candidate · clear top-down answerThe client saves an edit locally, sends it to a nearby realtime server, and receives an acknowledgement only after the edit reaches a durable log. Other users see it through the live room. Background workers build snapshots and run document checks. Publishing follows a separate path: validate one snapshot, its references, and its approvals in a database transaction, then create a fixed revision for downstream systems.
Why this mattersTracing one real request proves the boxes connect. It also exposes where we acknowledge success and where a retry may begin.
Candidate · clear top-down answerText merging is not enough for structured documents. Each edit says what it means: move this block, change this field, or add this link. Moving a block and editing its text can merge, but deleting a required block while another user links to it creates a business conflict. We preserve both edits, show the conflict, and block publishing until a person resolves it. Automatic convergence does not mean the document is semantically valid.
Why this mattersThe deep dive starts only after the basic path is clear. Use one concrete example, then state the speed-versus-correctness choice.
Candidate · clear top-down answerComments point to a stable block plus positions that move with the text. If the block is deleted, the comment becomes orphaned but is not lost. Suggestions are small edit sets, so people can preview and accept them safely.
Why this mattersAnchors need stable identity plus a clear orphan state. Silently attaching a comment to nearby text would preserve the UI while changing its meaning.
Candidate · clear top-down answerDraft edits may arrive more than once and a little out of order; stable edit IDs make repeats harmless. Publishing is stricter: it checks the exact content hash and approvals in one transaction so only the reviewed version can ship.
Why this mattersUse immediate agreement only for decisions that cannot be ambiguous. Let rebuildable views catch up and always show their freshness.
Candidate · clear top-down answerAn offline agent returns a suggestion based on an old version, never a full document replacement. Stable block IDs let us apply independent edits. Anything that targets deleted or changed blocks becomes a visible conflict for a person.
Why this mattersA failure answer should name the uncertain state first. Then explain how the system learns the truth before it repeats an action.
Candidate · clear top-down answerFor a very busy document, assign the room to one ordered stream, combine tiny updates into frames, and cap each user's buffer. A slow client gets a fresh snapshot plus missing edits instead of forcing the server to hold unlimited history in memory. Reconnects use randomized delay, and room ownership moves with a numbered lease so two servers cannot both accept writes after failover.
Why this mattersBusy tenants and large jobs need limits. Reserved capacity keeps one customer or one import from delaying everyone else's live work.
Candidate · clear top-down answerApprovals belong to an exact content hash. If an agent changes a required block, the old approval becomes stale. Publishing either writes exactly the reviewed content or fails and asks the user to review again.
Why this mattersAn approval covers exact bytes, not a moving document name. The hash check turns a subtle race into a safe, visible request to review again.
Candidate · clear top-down answerCheck permission when a user joins, reconnects, publishes, or exports. Every database, cache, room, and log key includes the customer ID. Agent tokens are short-lived and limited to one project, document, and action. Document text is untrusted data, never an instruction to a tool, so an agent cannot gain permission from text someone typed into the document.
Why this mattersSecurity belongs in keys, tokens, workers, and logs. It is not a single box added to the diagram at the end.
Candidate · clear top-down answerMeasure edit acknowledgement time, peer update time, reconnect time, publish conflicts, lost comment anchors, and whether every replica reaches the same result. Launch single-user editing first, then online collaboration, offline work, and finally agents.
Why this mattersMetrics should cover user speed, system safety, and result quality. Rollout starts read-only and earns stronger automation with evidence.
Candidate · clear top-down answerOffline support makes the merge logic complex. If offline editing is not important, a simpler server-ordered design may be better. Never use the moving draft as a release input; always publish one fixed revision.
Why this mattersEvery design choice has a cost. Name the simpler alternative and explain which requirement makes the added complexity worth it.
Candidate · clear top-down answerIn short: drafts are fast, local, and mergeable; published versions are fixed and carefully checked. Stable block IDs preserve meaning, agents only suggest changes, and one strong publish step turns a changing draft into trusted input.
Why this mattersThe recap should repeat the user flow, the main trust rule, the hardest failure, and the most important trade-off—not every component.
DOMAIN DEPTH
These mechanisms are the interview’s differentiators. Be able to redraw each from memory and defend its failure behavior.
Draft collaboration optimizes availability and convergence. Publication optimizes reviewability, invariants and stable downstream references.
Identity and relative positions survive routine editing; explicit orphan states preserve context when their target disappears.
FAILURE MATRIX
When the interviewer injects a fault, restate the violated assumption, change state or protocol, and name the new invariant.
| Injection | Recovery mechanism | Tempting wrong answer |
|---|---|---|
| 01Duplicate/offline ops | actor sequence + clientOpId dedupe | Double insert |
| 02Slow client | Bound buffer; send catch-up cursor | Room memory blow-up |
| 03Hot document | Scale fan-out; preserve one logical op order | Split brain |
| 04Stale agent patch | Rebase preview or explicit conflict | Whole-doc overwrite |
| 05Approval race | Bind approval to content hash; serializable publish | Unreviewed content ships |
| 06ACL revoked | Epoch-fence socket and caches | Stale connection reads |
BOTEC
Use orders of magnitude to expose the bottleneck. State what this simple model omits.
INTERACTIVE SCENARIO
Tune mock peak operation rate, size and granular retention. The result is a deliberately conservative peak-sustained bound; approved revisions are separate.
OPERATIONS + DELIVERY
A system is incomplete without observable user outcomes, staged deployment, rollback and an answer to “how will we know?”
INTERVIEWER TRAPS
Use these as flash cards. The right column is the compact sentence you want available under pressure.
| Trap | Better move |
|---|---|
| CRDT = semantic correctness | Validate domain invariants separately. |
| Character-offset comments | Use stable block + relative text anchors. |
| Approval of “latest” | Bind it to immutable content hash. |
| Agent replaces whole doc | Require typed patch with base clock. |
| Presence in the audit log | Keep it ephemeral and expiring. |
| Socket authorized forever | Fence sessions with ACL epochs. |
DEFINITIONS
Define the term, then connect it to a concrete invariant in this design. Avoid dropping vocabulary as a substitute for reasoning.
FINAL MINUTE
LivingSpec keeps a highly available convergent draft and a strongly controlled published truth. Clients optimistically apply typed CRDT operations; a document-partitioned log durably orders accepted ops, materializers snapshot and validate them, and ephemeral presence stays outside truth. Stable block IDs preserve moves, comments use relative anchors, and agents submit reviewable patches against base clocks. Publication validates schema, references, approvals and expected content in one transaction, producing an immutable hash. Epoch fencing, dedupe, convergence fuzzing and gradual rollout make human-plus-agent collaboration trustworthy.
Rehearse again