Phase 5 assessment · System Architect

Strong

Transition table.

From	Command	To	Actor	Rule
—	reserve	reserved	the returns service, on acceptance	one settlement per accepted return; amount is the refundable total at acceptance
reserved	reduce	reserved	a support agent	at most once; a reason is required; the new amount must be lower and above zero
reserved	authorize	authorized	warehouse intake	the received item matches a line on the return
reserved	lapse	lapsed	a scheduled job, 21 days after reservation	nothing has arrived; the clock is the reservation date, not the return request date
authorized	settle	paid	the payment provider’s confirmation	idempotent on the settlement id; a repeat confirmation is not a second payment

Side effects and recovery. reserve: no external effect; reversible by deleting the reservation. reduce: no external effect, but it is customer-visible once communicated; reversible in the data and awkward in the conversation, so the rule allows it once. authorize: none outside our boundary; reversible. lapse: sends a customer notification, which cannot be unsent — recovery is a forward transition, not a reversal. settle: moves money. There is no reversal at all; the description says so, and the honest table records “recovery: none within this system; raising a debt is a separate process with a different owner”. That row is the most important one in the table, because it marks the moment after which mistakes stop being ours to fix.

Two things the description does not answer, and I am not inventing: what happens when an item arrives after lapsing (day 23), and whether reduce is available after authorizing. Both go to finance as questions rather than into the table as guesses. The day-23 case is not hypothetical — carriers lose things and then find them.

History: audit trail, not event sourcing. The question people will actually ask is “why was this settlement lower than the order total, and who reduced it?” — support asks it, and finance asks it at month end. That needs who, when, from, to, and the reason string, which is a transitions table beside the current state. Full event sourcing would also answer it, at the price of replay, read models, event-schema evolution and tooling, none of which any current question needs. If regulatory reconstruction of the whole settlement lifecycle is ever required, that is the evidence that would change this — and it would be a new decision record, not a quiet migration.

Strong

Internal contract.

from typing import Protocol


class EligibilityPolicy(Protocol):
    """Decides whether a return may proceed.

    Promises:
      - exactly one decision per (return, evidence) pair; calling twice with
        the same evidence returns an equal decision
      - a refusal is a value, not an exception: Decision.refused carries a
        machine-readable reason and a customer-safe explanation
      - raises only when it cannot decide (evidence unavailable), never
        because the answer was no
    """

    def assess(self, request: ReturnRequest, evidence: OrderEvidence) -> Decision: ...

The promise a type cannot express is determinism, so that is what the test pins:

def test_assess_is_deterministic_for_the_same_evidence():
    policy = StandardEligibilityPolicy(window_days=30)
    request = a_return(placed_days_ago=31)
    evidence = order_evidence(total=Money("40.00", "EUR"))

    first = policy.assess(request, evidence)
    second = policy.assess(request, evidence)

    assert first == second
    assert first.refused
    assert first.reason is RefusalReason.OUTSIDE_WINDOW

External contract. POST /returns/{id}:assess — a custom method, because assessing is a domain verb and not the creation of a resource. Identity: the caller sends an Idempotency-Key minted when the customer presses the button and reused across retries; the same key returns the first decision, byte for byte. Errors carry a stable code, a human message, and a retryable boolean. Crucially, a refusal is 200 with a refused decision, not 4xx: the request was valid and the system answered. Reserving 4xx for malformed input and 5xx for “could not decide” keeps the mobile client’s error handling and the business’s refusal rate in different places.

Compatibility policy, as consumers may quote it. We may add optional response fields at any time. We may add values to reason with 30 days’ notice; consumers must treat unrecognized reasons as a generic refusal and must not switch exhaustively. We will never change the meaning of an existing field, remove a field, or make an optional request field required, without a new version and a 90-day overlap. Breaking is defined by that list, not by judgement.

The three changes.

Change	Breaking?	Who finds out first
An optional estimated_refund field is added	No, under the policy	Nobody, if consumers are tolerant readers. A consumer validating against a closed schema breaks immediately — which is why the policy states the tolerant-reader requirement rather than assuming it
A new reason value, HAZARDOUS_ITEM	Not under the policy, and only because the policy said so in advance	The mobile app, in whichever release ships after the value first appears. This is why the 30-day notice exists and why we run the contract test against the app’s pinned fixtures
refundable_total starts excluding shipping	Yes, and the worst kind: the schema does not change	Nobody, technically. Support finds out three weeks later from customers disputing amounts. Nothing in a type system or a schema registry catches this, so the only defense is the policy’s explicit prohibition plus a semantic contract test that asserts the field includes shipping

The third row is the point of the exercise. Two of these changes are caught by machinery; the expensive one is caught only by a written rule that somebody remembers to apply.

Strong

Style: a modular monolith with one asynchronous edge. One deployable containing three modules with enforced import boundaries — eligibility, settlement, logistics — plus one worker process for carrier labels, fed from an outbox table written in the same transaction as the acceptance.

Driver by driver. Driver 2 (never inconsistent) puts the eligibility decision and the refund reservation in one aggregate and one transaction; that is the single decision that rules out splitting them across processes. Driver 3 (carrier outage) is the one thing that must not be synchronous, so it is the one asynchronous edge: acceptance writes the label intent to the outbox and commits, and the worker drains it. Driver 1 (800 ms) is comfortable in-process, and the fraud call inside it gets a 400 ms timeout with a manual-review fallback. Driver 4 (reversible in 10 minutes) is why there is one deployable and one pipeline: a single revert, and no cross-service version matrix. Driver 5 (six people, four weeks) is why the boundaries are import rules rather than network calls — the seams exist, and nobody pays the operational cost of them yet.

The boundaries are real, not decorative: three Python packages, an allowed-import table, and a test that fails the build when it is violated. Deployable boundaries: two, the web process and the label worker. Everything else is a compile-time boundary that could become a deployable one later without changing its interface, which is the only thing that makes “later” credible.

Rejected: three services, one per module. It genuinely wins on driver 5’s second half if the team ever grows past one squad, and on independent scaling of eligibility, which is the only module with a latency driver. The cost of rejecting it: the day a second team owns settlement, we will pay for an extraction we could have had for free now. The cost of choosing it: driver 2 becomes a distributed transaction or a compensation path, driver 4 becomes a three-service rollback with a version matrix, and driver 1’s budget starts paying two network hops — all inside four weeks and six people. I would rather pay the extraction later, with evidence, than the operations now, on a guess. Revisit when a second team takes ownership of any module, or when eligibility’s scaling needs diverge from the rest by more than a factor of three.

Release path.

Step	Deployed	Gate	Reversal
1	Schema expansion: returns tables and outbox, nothing reads them	migration runs on a production-sized copy in under 2 minutes	drop, since nothing reads them
2	Whole system dark: routes registered, feature flag off	synthetic transaction passes end to end in production	flag is already off; revert the deploy
3	Internal users only, by allow-list	20 real returns completed by staff, zero manual interventions	empty the allow-list — seconds, no deploy
4	5% of eligible customers	outcome dashboard live: median resolution time and support-contact rate, compared with the same weekday last week; p95 under 800 ms; manual queue under 50 a day	flag to 0%; accepted returns already in flight continue, which is why the flag gates entry and not processing
5	25%, then 100%	two consecutive weeks inside every guardrail	flag percentage down; the data written stays valid either way

Every step reverses by a flag or a deploy, and none needs a restore, which is driver 4 satisfied by construction rather than by hope. The one exception is step 1’s migration, which is expansion only — and the contraction that eventually drops the old columns is deliberately after the pilot, because it is the only irreversible move in the plan and it is not needed to launch.

Temporary machinery, with its removal condition. The returns_v2 flag: removed when it has been at 100% for two weeks. The staff allow-list: removed at step 5. The dual-read shim over the old returns table: removed once the finance export has been reconciled against the new source for a full month. All three are on the closeout checklist with owners, because the flag that nobody removes is the config debt lesson 0035 warns about.