Build a versioned shared document editor

Application background

Several incident responders type into the same shared document. Each browser starts from a saved version of the text. If two people edit that version at once, accepting both complete replacements would silently discard somebody's work.

Start with an editor that reports this conflict clearly. Automatic merging can come later. The server must also keep an edit it has already reported as saved if its process restarts.

Example walkthrough

A revision is a saved version of the document. An operation log records accepted edits so reconnecting clients and restarted servers can recover what happened.

Your assignment

Deliver: Build a shared document with saved revisions and edit history. Accept edits against the correct revision and preserve a user's draft when a conflict occurs.

Required behavior: An acknowledged edit is durable and assigned a document revision. The first milestone accepts an edit only against its stated base revision. Stale edits remain as local drafts with an explicit conflict. Presence and cursors are best-effort.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/collaborative_editor.py

Supplied file: examples/architecture-starts/collaborative_editor.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for collaborative-editor. No AWS resources are created."""
doc={'revision':12,'text':'Incident draft'}; accepted={}
def edit(op,base,text):
    if op in accepted: return accepted[op]
    if base!=doc['revision']: return {'status':409,'server_revision':doc['revision'],'keep_draft':text}
    doc.update(revision=base+1,text=text); accepted[op]=dict(doc); return accepted[op]
print(edit('ana-1',12,'Ana update'))
print(edit('ben-1',12,'Ben offline draft'))
print(edit('ana-1',12,'Ana update'))

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

{'revision': 13, 'text': 'Ana update'}
{'status': 409, 'server_revision': 13, 'keep_draft': 'Ben offline draft'}
{'revision': 13, 'text': 'Ana update'}

Set up your implementation workspace

Create work/collaborative-editor/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Build a versioned save protocol

Implement GET document and POST operation with base revision and operation identity. Commit accepted operation and new revision together. Keep the losing draft visible and support a manual merge against the latest revision. This is a useful working baseline, not a claim of conflict-free editing.

2. Add live operation delivery

Broadcast only committed operations. Clients track the last applied revision and fetch missing ranges on reconnect. Apply duplicate operation IDs once. Store snapshots with a proven last included revision so replay neither skips nor doubles an edit.

3. Choose an actual merge algorithm

For automatic concurrent editing, choose a maintained OT or CRDT implementation and document its operation identities, causal metadata and persistence format. Do not invent string-offset merging after the fact. Deletion and insertion offsets change under concurrent edits.

4. Bound offline and presence state

Specify the supported offline duration and history/metadata retention required by the chosen algorithm. Expire presence independently. A user removed from the document cannot upload old offline edits without a current authorization check.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

The operation log is durable. Presence is disposable. ECS exposes the stateful session and ordering problem clearly. A managed synchronization product can replace parts of this design, but its conflict and offline semantics must still match the product.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Merge offline edits using stable character identities

Integer character offsets describe a particular document version. After one user deletes a character, the other user's insert-at-position-1 can refer to a different place. A box named merge does not settle this ambiguity.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. For a small demonstrator, implement a sequence with immutable character IDs, insertion anchors and deletion tombstones. Define a deterministic sibling ordering, such as the ordered pair of logical counter and client ID. Retain deleted anchors while offline operations may reference them. This is an explicit toy operation model, not a complete text-editor CRDT. Replacing it with a library still requires a documented operation format and snapshot/history-expiry behavior.

Walk through the result. Start with A(id=a) followed by B(id=b). Alice emits delete(b). Bob emits insert(id=x, after=b, value=X). With tombstoned anchors retained, applying either order gives AX. Then let both insert after a and show the tie-break rule yields the same result on both replicas. Supply the operations and resulting character-ID sequence.

Allow two offline users to delete and insert at the same position. Show the chosen algorithm’s actual operation data and convergence rule. A diagram labeled merge is not enough to define the result.