SD12.6 · LESSON 6 OF 6

Design review

Produce an end-to-end design whose data paths, capacities and failure behavior satisfy explicit requirements.

THE IDEA

Design review

A design review submits requirements, capacity estimates, the architecture, request sequences, the schema, a failure analysis and the trade-offs, and then tests the claimed invariant. Two concurrent completion requests that each check "already awarded?" and then write can run in 6 different interleavings, and 4 of them award XP twice; an atomic insert-if-absent awards once in all six. A single concrete counterexample beats a diagram full of boxes.

order of the 4 steps	XP awarded
A.check, A.write, B.check, B.write	20
A.check, B.check, A.write, B.write	40 ← double award
A.check, B.check, B.write, A.write	40 ← double award
B.check, A.check, A.write, B.write	40 ← double award
B.check, A.check, B.write, A.write	40 ← double award
B.check, B.write, A.check, A.write	20

6 interleavings, 4 violate "never more than 20 XP" counterexample: A.check, B.check, A.write, B.write A review should list requirements, capacity estimates, the architecture, request sequences, schema, failure analysis and trade-offs, and test the claimed invariant with a concrete interleaving like this one.

Switch between check-then-act and an atomic insert.

Predict first. Does a diagram full of components establish that a system meets its objectives?

Chapter context

A case study integrates choices into one coherent system. Start with a small requirement set, trace the important operations, calculate the dominant costs and stress the design with a failure before adding components.

TRY IT YOURSELF

Part 1. Do it hands-on

Enumerate the interleavings by hand, then write a checker that finds the counterexample.

order of the 4 steps	XP awarded
A.check, A.write, B.check, B.write	20
A.check, B.check, A.write, B.write	40 ← double award
A.check, B.check, B.write, A.write	40 ← double award
B.check, A.check, A.write, B.write	40 ← double award
B.check, A.check, B.write, A.write	40 ← double award
B.check, B.write, A.check, A.write	20

interleavings of two 2-step requests of them that double-award XP for A.check, B.check, A.write, B.write a component diagram proves the objectives? (yes/no)

To do: Two concurrent requests each do check (is XP already awarded?) then write (award 20 XP). In how many different interleavings can the 4 steps run, keeping each request's own order? C(4,2)
To do: In how many of those does a check-then-act implementation award XP twice? (Only the two fully serial orders are safe.)
To do: Take the order A.check, B.check, A.write, B.write. Total XP with check-then-act?
To do: Does a diagram full of components establish that a system meets its objectives? Type yes or no

Part 2. Do it in code

interleavings(a, b): all merges of two step lists that keep each list's own order (lists of steps).
run_check_then_act(order): steps are (request, "check") or (request, "write"). A check records whether the user was NOT yet awarded. A write awards 20 XP (and marks the user awarded) if that request's check said "not yet awarded". Return the final XP.
run_atomic(order): same steps, but the write is an atomic insert-if-absent: it awards 20 XP only if nobody has awarded yet (checks are ignored).
double_award_orders(a, b, runner): the interleavings for which runner returns more than 20 XP.
invariant_holds(a, b, runner): True if the runner never exceeds 20 XP in ANY interleaving.
counterexample(a, b, runner): the first interleaving that breaks the invariant, or None.

import itertools

def interleavings(a, b):
    pass

def run_check_then_act(order):
    pass

def run_atomic(order):
    pass

def double_award_orders(a, b, runner):
    pass

def invariant_holds(a, b, runner):
    pass

def counterexample(a, b, runner):
    pass

Ctrl/⌘ + Enter runs it

Stuck, or something not working? You can come back to it any time.

CHECK YOUR UNDERSTANDING

Does a diagram full of components establish that a system meets its objectives?

ANoBYes

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

For first-completion XP, define a unique logical event key such as (user_id, lesson_id, reward_version). Under a fixed reward r, $XP=r\times$ count(distinct eligible event keys). The deduplication record and awarded effect must share an atomic durable boundary in a real implementation.

Worked example

One hundred learners complete the same lesson, and every completion request is retried once. There are 200 deliveries but only 100 distinct learner-lesson events. At 20 XP per first completion, the correct total is 2000 XP, not 4000. The Python example models the invariant without pretending to implement distributed persistence.

Reference code

The following example uses the Python standard library and does not call a remote service.

deliveries=[]
for user in range(100):
    deliveries.extend([(user,'lesson-1','reward-v1')]*2)
unique=set(deliveries)
assert len(deliveries) == 200
assert len(unique) == 100
assert 20*len(unique) == 2000
assert 20*len(deliveries) == 4000

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

A keyspace count does not prove collision freedom. Delivery and reading are different product events. Deduplication must cover both durable event identity and the actual effect.