Document modules — document-design-system

Key point

.keypoint

One sentence the reader should carry out of the section.

Allowed in: every pattern
Used in 7 examples: Design doc, Explanation, mulesoft, Onboarding, Postmortem, Statement of work, Support model

Runbooks own execution; this page owns who responds and when.

Specimen from the Support model.

Evidence note

.evidence

Source and evidence state for the claim just made.

Allowed in: every pattern
Used in 6 examples: Architecture decision record, Architecture guide, Design doc, Postmortem, Proposal, Test report

Verified from the incident register and 2026-08-12 inventory snapshot.

Specimen from the Proposal.

Figure

.figure

Captioned diagram or chart.

Allowed in: every pattern
Used in 5 examples: Delivery plan, Basis of estimate, Migration and cutover plan, Platform primer, Runbook

Bridge from work packages to the expected total. CR-003 is drawn, not added.

Specimen from the Basis of estimate.

Table scroll

.table-scroll

Wide table that scrolls inside itself on narrow screens.

Allowed in: every pattern
Used in 17 examples: API contract, Change request, Design-to-engineering handoff, Basis of estimate, mulesoft, Platform primer, Postmortem, Production readiness review, Reference, Risk and RAID register, Service documentation suite, Specification, Statement of work, Support model, Test report, Threat model, Workshop summary

Reliability	Decide RAID-02 by 2026-09-01
Platform	Confirm chaos owner by 2026-09-18
Producer teams	Supply fixtures by 2026-10-16

Specimen from the Workshop summary.

Footnotes

.footnotes

Sources and asides kept out of the reading line.

Allowed in: every pattern
Used in 0 examples: No example yet

Incident tickets for 2026-03-14, 2026-04-02, 2026-06-19 and 2026-07-30. Verified.
Normalized inventory export, as of 2026-08-12. 1.84M of 2.50M units.

No example uses this module yet; this specimen is written for this page.

Section number

.section-num

Numbered section marker inside a section head.

Allowed in: every pattern
Used in 15 examples: Architecture decision record, Architecture guide, Design doc, Design-to-engineering handoff, Discovery brief, Explanation, Engineering handoff, How-to guide, mulesoft, Onboarding, Platform primer, Postmortem, Proposal, Runbook, Tutorial

01

The working model

8 min

Specimen from the Onboarding.

Reading time

.reading-time

Time or role label at the end of a section head.

Allowed in: every pattern
Used in 15 examples: Architecture decision record, Architecture guide, Design doc, Design-to-engineering handoff, Discovery brief, Explanation, Engineering handoff, How-to guide, mulesoft, Onboarding, Platform primer, Postmortem, Proposal, Runbook, Tutorial

01

The working model

8 min

Specimen from the Onboarding.

Non-goals

.non-goals

What this document deliberately does not decide or cover.

Allowed in: Decision, Contract, Plan
Used in 2 examples: Design doc, Specification

Authentication, payload schema, warehouse writes, batch ingestion, and global ordering are outside this specification.

Specimen from the Specification.

Checkpoint

.checkpoint

Observable state that proves the reader may continue.

Allowed in: Learning, Procedure
Used in 2 examples: Runbook, Tutorial

Checkpoint: contract and consumer suites pass. If they do not, stop here; the tutorial should not teach around a broken baseline.

Specimen from the Tutorial.

Section takeaway

.takeaway

The per-section conclusion, stated after the material that earns it.

Allowed in: Learning, Procedure, Incident, System, Suite
Used in 10 examples: Design-to-engineering handoff, Explanation, Engineering handoff, How-to guide, mulesoft, Onboarding, Platform primer, Postmortem, Runbook, Tutorial

If a design or incident response crosses one of these boundaries, stop and open the owning contract or runbook before acting.

Specimen from the Onboarding.

Danger

.danger

Irreversible or unsafe action, before the step that risks it.

Allowed in: Procedure, Contract, Plan, Assurance
Used in 5 examples: API contract, Engineering handoff, How-to guide, Migration and cutover plan, Production readiness review

A blocking criterion moves 2026-11-02. Any waiver needs an owner and expiry.

Specimen from the Production readiness review.

Specimen

.specimen

Exact request, payload, or command with a caption.

Allowed in: Contract, Learning, Procedure, System
Used in 5 examples: API contract, Onboarding, Platform primer, Specification, Tutorial

routingevent.id = "evt_01"
hash(event.id) mod 2 = 0
destination = ingest-a
result = enqueued

A repeat of evt_01 resolves to the same queue.

Specimen from the Specification.

Comparison grid

.comparison-grid

Options or distinctions judged on the same criteria.

Allowed in: Decision, Record, Learning, Incident
Used in 9 examples: Architecture decision record, Change request, Design doc, Discovery brief, Explanation, Onboarding, Postmortem, Project charter, Proposal

In

Dispatcher, two queues and consumer groups, operator overview, chaos evidence, runbooks, release, and handoff.

Out

Payload, authentication, warehouse schema, batch path, and retention.

Specimen from the Project charter.

Ask band

.ask-band

The decision asked for, by whom, by when, and the default if declined.

Allowed in: Decision
Used in 2 examples: Design doc, Proposal

The ask

Fund two Platform engineers for one quarter

Release only when one failed queue cannot stall the other.

Decide by: 2026-09-01
Decider: Platform director
If declined: Record the single queue as an accepted risk

Specimen from the Proposal.

Decision grid

.doc-grid

Argument column beside the decision rail.

Allowed in: Decision
Used in 6 examples: Change request, Design doc, Discovery brief, Basis of estimate, Project charter, Proposal

Baseline versus requested change

Baseline

Live state only

The operator overview shows current queue status and links to the runbook.

CR-003

Seven-day history

Add event history and move the extended onboarding lab one week after handoff.

Impact ledger

Effort	3 engineer-weeks
Production	Stays 2026-11-02 under option 1
Quality	Design-handoff acceptance required
Baseline	RFC 014 and 24 engineer-weeks until approval

Specimen from the Change request.

Decision rail

.decision-rail

Sticky brief: the ask, guardrails, open questions.

Allowed in: Decision
Used in 6 examples: Change request, Design doc, Discovery brief, Basis of estimate, Project charter, Proposal

Specimen from the Basis of estimate.

Scope strip

.scope-strip

Who it is for, read time, companion documents, and what it is not.

Allowed in: Learning, Decision, Brief, System
Used in 1 example: Platform primer

For: Engineers joining Platform from the batch and warehouse side
Read time: 25 minfive sections, no setup
Read with: Onboarding to run it, the explanation for why it halts, the runbook when lag rises
This is not: A setup checklist, an operating procedure, or the RFC 014 decision

Specimen from the Platform primer.

Crosswalk

.crosswalk

Term in the reader's world mapped to the term here, with fit and note.

Allowed in: Learning, Decision, Contract, System
Used in 1 example: Platform primer

Batch term → term here, with how well the batch intuition fits
In batch	Here	Fit	What to adjust
Target table	Warehouse	Holds	The same warehouse analytics and operations read. Its schema is outside RFC 014.
Loader job	Consumer group, three replicas	Holds	Validates and writes events to the warehouse. Scale it one replica at a time.
Landing area	Queue `ingest`	Partial	Holds work between arrival and load, but it is shared by every producer, has no failover, and keeps events for 24 hours.
Rerun	Retry with the same event ID	Partial	Producers retry single events. Repeating an accepted ID must not create a second warehouse row; a new ID makes a second event.
Freshness check	Lag, `ingest_lag_seconds`	Partial	Freshness is how far consumers trail arrivals, not whether a job finished.
Schedule	None on this path	Breaks	Nothing waits for a trigger. Scheduled file imports still exist, on the separate batch path.
Load window	`202` at the gateway	Breaks	There is no window to finish inside. The gateway answers each event as soon as the queue accepts it.
Failed run	Shared-queue halt	Breaks	A failed batch run stops its own load. A full queue stops Checkout, Catalog, and Inventory together.

Holds your intuition is rightPartial right shape, different limitsBreaks unlearn it here

Specimen from the Platform primer.

Learning goal

.learning-goal

What the reader will be able to do or explain at the end.

Allowed in: Learning
Used in 4 examples: Explanation, Onboarding, Platform primer, Tutorial

Learning goal · 20 minutes

By the end, you can

start the local gateway from a known-good build;
send one synthetic event and read its acceptance;
explain why a retry keeps the same event ID.

Specimen from the Tutorial.

Decision statement

.decision-statement

The settled choice in one block.

Allowed in: Record
Used in 1 example: Architecture decision record

The dispatcher will compute hash(event.id) mod 2. Even partitions go to ingest-a; odd partitions go to ingest-b.

Specimen from the Architecture decision record.

Consequence grid

.consequence-grid

What the choice makes easier and harder.

Allowed in: Record
Used in 1 example: Architecture decision record

Benefits

Dominant producers distribute across both queues.
Retries route to the same partition.
One queue failure leaves a useful healthy path.

Costs

Producer replays must read both queues.
Callers cannot infer ordering from queue placement.
Runbooks and dashboards must name the partition.

Specimen from the Architecture decision record.

Contract layout

.contract-layout

Index column beside the normative text.

Allowed in: Contract
Used in 6 examples: API contract, Reference, Requirements specification, Specification, Statement of work, Support model

Coverage and intake

Platform owns business-hours support and the existing on-call path for P1/P2 incidents. Operator questions use the service channel; alerts page on-call.

Priority matrix

Priority	Definition	First owner
P1	Acceptance stopped for multiple producers	Platform on-call
P2	One queue impaired or lag rising	Platform on-call
P3	Non-urgent defect or documentation gap	Platform backlog

Escalation and boundaries

After 15 minutes without falling lag, or on any crash loop, Platform escalates to Reliability and stops replica changes. Checkout, Catalog, and Inventory own payload quality. Warehouse schema stays outside the service.

Runbooks own execution; this page owns who responds and when.

Specimen from the Support model.

Contract index

.contract-index

Sticky list of rules or sections.

Allowed in: Contract
Used in 6 examples: API contract, Reference, Requirements specification, Specification, Statement of work, Support model

Specimen from the Requirements specification.

Requirement

.requirement

Identified rule with its condition.

Allowed in: Contract, Assurance
Used in 4 examples: API contract, Requirements specification, Specification, Test report

REQ-104

Every response must echo X-Request-Id.

Specimen from the Requirements specification.

Endpoint

.endpoint

Method and path with its behaviour.

Allowed in: Contract
Used in 2 examples: API contract, Reference

GET

`/health/live`

Process is running. Does not prove queue access.

Specimen from the Reference.

Procedure steps

.procedure-steps

Numbered steps on a rail.

Allowed in: Procedure, Learning
Used in 4 examples: Engineering handoff, How-to guide, Onboarding, Runbook

Run the tests
```
bashmake ingest-test
```
Success: contract and consumer tests pass.
Start the gateway
```
bashmake ingest-run
```
Success: the log contains listening on 8443.

Post the synthetic event

bashcurl -k https://127.0.0.1:8443/events \
  -d '{"id":"evt_learn","type":"onboarding.ping"}'

Success: 202 repeats evt_learn.

Specimen from the Onboarding.

Outcome

.outcome

Observable success after a step.

Allowed in: Procedure, Learning
Used in 4 examples: Engineering handoff, How-to guide, Onboarding, Runbook

Success: contract and consumer tests pass.

Specimen from the Onboarding.

Response band

.response-band

Parallel responses side by side: verify, roll back, escalate.

Allowed in: Procedure
Used in 1 example: Runbook

Verify

Close only on sustained recovery

Lag falls for ten minutes and POST /events p99 remains below 200 ms.

Rollback

Remove the added replica

Return to the previous count if the new replica causes errors. Never delete queues.

Escalate

Stop local changes

After 15 minutes, any crash loop, or rising 5xx: page Platform primary and Reliability.

Specimen from the Runbook.

System map

.system-map

Framed architecture figure.

Allowed in: System, Decision, Learning
Used in 5 examples: Architecture guide, Design doc, Design-to-engineering handoff, Onboarding, Platform primer

Specimen from the Architecture guide.

System layout

.system-layout

Map column beside the boundary rail.

Allowed in: System
Used in 1 example: Architecture guide

01

Containers and responsibilities

current

Gateway

Identity and acceptance

mTLS, audience claim, envelope validation, request correlation, and queue write.

Queue

Shared 24-hour buffer

ingest holds every first-party event and has no failover.

Consumer group

Validate and land

Three normal replicas read the queue and write the warehouse.

Warehouse

Downstream record

Stores accepted events; schema ownership sits outside Platform.

02

Primary runtime path

sequence

Producer sends an event with stable event ID and request ID.
Gateway authenticates, validates, and writes to ingest.
Gateway returns 202 after queue acceptance.
A consumer validates the event and writes the warehouse.
Lookup and freshness expose later state; they are not part of acceptance.

03

Failure and recovery boundaries

risk

Consumer slowdown

Lag and queue depth rise.

Queue saturation

The single buffer stops accepting.

Gateway overload

Every producer blocks or receives 503.

Adding one consumer replica is the safe local recovery control. Because every producer shares the queue, current recovery is also shared.

04

Runtime placement

deployment

The gateway and ingest-consumer run in namespace ingest on prod-ingest; staging mirrors the namespace on stage-ingest. Replica changes are the only scaling control operators own.

05

Trust and data boundaries

security

The gateway terminates producer identity and enforces the audience claim.
Event bodies remain opaque to routing; domain validation belongs to gateway schema and consumers.
Queue and warehouse credentials are runtime secrets, never document content.
The proposed dispatcher inherits gateway identity and adds no body store.

Specimen from the Architecture guide.

System rail

.system-rail

Boundaries, owners, and interfaces beside the map.

Allowed in: System
Used in 1 example: Architecture guide

Specimen from the Architecture guide.

State grid

.state-grid

One card per state the reader must handle.

Allowed in: System
Used in 2 examples: Architecture guide, Design-to-engineering handoff

Happy

All queues written as healthy; lag and shed values visible.

Idle

No recent events; explain that zero traffic is not a failure.

Loading

Reserve layout and announce refresh without presenting stale values as current.

Partial data

Show available queues and name the missing source.

Error

Written failure, last known update, retry behavior, and runbook link.

Recovered

Success label with recovery time; avoid celebratory animation during incidents.

Specimen from the Design-to-engineering handoff.

Impact strip

.impact-strip

Three headline measures before any narrative.

Allowed in: Incident, Decision, Assurance
Used in 3 examples: Basis of estimate, Postmortem, Test report

24engineer-weeks expected

22–28engineer-week range

Mediumconfidence

Specimen from the Basis of estimate.

Timeline

.timeline

Timestamped reconstruction.

Allowed in: Incident
Used in 1 example: Postmortem

14:12
Detected. Lag crossed 120 seconds for five minutes; the on-call page fired.
14:18
Scoped. Consumers were alive, but queue depth continued to rise faster than drain rate.
14:31
Mitigated. The on-call added one consumer replica. Lag flattened briefly, then resumed climbing.
15:40
Escalated. Gateway requests began timing out; every producer entered hard failure.
16:04
Recovered. A second scale-up drained the queue and producer acceptance returned.
17:22
Validated. Warehouse freshness returned below ten minutes and no replay gap remained.

Specimen from the Postmortem.

Cause chain

.cause-chain

Cause to effect in reading order.

Allowed in: Incident, Learning, System
Used in 3 examples: Architecture guide, Explanation, Postmortem

Consumer slowdown

Lag and queue depth rise.

Queue saturation

The single buffer stops accepting.

Gateway overload

Every producer blocks or receives 503.

Specimen from the Architecture guide.

Action register

.action-register

Owned corrective actions.

Allowed in: Incident
Used in 1 example: Postmortem

Corrective action register
Action	Owner	Due	Proof
Split ingestion into two independently recoverable queues	Platform	2026-09-30	Chaos test isolates one failed queue
Page at 60 seconds of lag with producer blast radius in the message	Reliability	2026-08-21	Alert fixture and game-day page
Add bounded shed counts and retry guidance to the gateway dashboard	Platform	2026-09-05	Dashboard review with producer teams

Specimen from the Postmortem.

Document map

.document-map

Cards linking the documents in a set.

Allowed in: Suite, Procedure
Used in 3 examples: Engineering handoff, mulesoft, Service documentation suite

Behavior

`openapi/events.yaml`

Producer contract. It wins over the HTML companion.

Runtime

Deployment manifests

Replica counts, queue URI, health checks, and environment names.

Operations

Ingestion / lag

Lag, queue depth, request p99, shed count, and runbook link.

Specimen from the Engineering handoff.

Plan layout

.plan-layout

Plan column beside the gate rail.

Allowed in: Plan
Used in 3 examples: Delivery plan, Migration and cutover plan, Test strategy

Risk-led test layers

Contract

API and error behavior · Platform.

Component

Partition and warehouse writes · Platform.

Chaos

One queue down · Reliability.

Producer

Checkout, Catalog, Inventory retries.

Cutover

Reconciliation and rollback rehearsal.

Evidence schedule

2026-09-18
Entry
Chaos environment available.
Build
Trace
REQ-101 through REQ-105 linked to tests.
2026-10-28
Exit
No blockers; chaos executed; residual risk accepted.

Specimen from the Test strategy.

Plan gates

.plan-gates

Control gates and their criteria.

Allowed in: Plan
Used in 3 examples: Delivery plan, Migration and cutover plan, Test strategy

Specimen from the Test strategy.

Milestone rail

.milestone-rail

Dated milestones in order.

Allowed in: Plan
Used in 3 examples: Delivery plan, Migration and cutover plan, Test strategy

2026-09-18
Entry
Chaos environment available.
Build
Trace
REQ-101 through REQ-105 linked to tests.
2026-10-28
Exit
No blockers; chaos executed; residual risk accepted.

Specimen from the Test strategy.

Workstream board

.workstream-board

One card per workstream.

Allowed in: Plan
Used in 3 examples: Delivery plan, Migration and cutover plan, Test strategy

Data

No duplicate warehouse row.

Latency

POST /events p99 stays below 200 ms.

Recovery

Lag falls for ten minutes.

Specimen from the Migration and cutover plan.

Assurance layout

.assurance-layout

Verdict column beside the evidence.

Allowed in: Assurance
Used in 4 examples: Production readiness review, Risk and RAID register, Test report, Threat model

Evidence matrix

Area	State	Evidence or gap
Ownership and support	Ready	Platform and Reliability agreed
Contract compatibility	Ready	Payload and authentication unchanged
Observability	Conditional	Blast-radius proof required
Failure isolation	Blocking	Chaos cases not executed
Rollback	Conditional	Production-like rehearsal required
Producer validation	Conditional	Fixtures due 2026-10-16

A blocking criterion moves 2026-11-02. Any waiver needs an owner and expiry.

Specimen from the Production readiness review.

Assurance verdict

.assurance-verdict

The verdict and its conditions.

Allowed in: Assurance
Used in 4 examples: Production readiness review, Risk and RAID register, Test report, Threat model

Specimen from the Risk and RAID register.

Verdict

.verdict

Inline verdict for one finding or test set.

Allowed in: Assurance
Used in 1 example: Test report

Evidence boundary

Functional and regression behavior passed on the current single-queue build. Release approval does not claim partial-failure isolation.

Specimen from the Test report.

Finding register

.finding-register

Findings with severity and owner.

Allowed in: Assurance
Used in 2 examples: Risk and RAID register, Threat model

ID	Threat	Control	Residual state
THR-01	Forged caller audience	mTLS + audience claim	Negative tests
THR-02	Replayed event ID	Idempotent write	Test both queues
THR-03	Queue-flood denial of service	Bounded shedding + isolation	RAID-02 unresolved
THR-04	Operator metadata exposure	Read-only least privilege	Review before go-live

Specimen from the Threat model.

Evidence matrix

.evidence-matrix

Claims against the evidence that supports them.

Allowed in: Assurance
Used in 1 example: Production readiness review

Area	State	Evidence or gap
Ownership and support	Ready	Platform and Reliability agreed
Contract compatibility	Ready	Payload and authentication unchanged
Observability	Conditional	Blast-radius proof required
Failure isolation	Blocking	Chaos cases not executed
Rollback	Conditional	Production-like rehearsal required
Producer validation	Conditional	Fixtures due 2026-10-16

Specimen from the Production readiness review.

Brief status

.brief-status

Current state in three cells.

Allowed in: Brief
Used in 4 examples: Incident update, Release notes, Delivery status report, Workshop summary

OverallAmberdecision + environment dependency

Forecast2026-11-02unchanged

Baseline24engineer-weeks

Specimen from the Delivery status report.

Brief grid

.brief-grid

Update cards for what changed and what needs attention.

Allowed in: Brief
Used in 4 examples: Incident update, Release notes, Delivery status report, Workshop summary

Mitigation underway

Platform is adding one consumer replica and observing lag for three minutes. No queue will be deleted and replica count will not exceed six without Reliability.

Escalation

After 15 minutes without falling lag, or on any crash loop, Platform pages Reliability and stops replica changes.

Specimen from the Incident update.

Next checkpoint

.next-checkpoint

When and where the next update lands.

Allowed in: Brief
Used in 4 examples: Incident update, Release notes, Delivery status report, Workshop summary

Specimen from the Incident update.

Action required

.action-required

The one action a reader must take.

Allowed in: Brief
Used in 2 examples: Incident update, Release notes

Producer action

Retry with bounds and preserve event IDs

Specimen from the Incident update.

The working model

The working model

In

Out

Fund two Platform engineers for one quarter

Baseline versus requested change

Live state only

Seven-day history

Impact ledger

By the end, you can

Coverage and intake

Priority matrix

Escalation and boundaries

/health/live

Run the tests

Start the gateway

Post the synthetic event

Close only on sustained recovery

Remove the added replica

Stop local changes

Containers and responsibilities

Identity and acceptance

Shared 24-hour buffer

Validate and land

Downstream record

Primary runtime path

Failure and recovery boundaries

Consumer slowdown

Queue saturation

Gateway overload

Runtime placement

Trust and data boundaries

Happy

Idle

Loading

Partial data

Error

Recovered

Consumer slowdown

Queue saturation

Gateway overload

openapi/events.yaml

Deployment manifests

Ingestion / lag

Risk-led test layers

Contract

Component

Chaos

Producer

Cutover

Data

Latency

Recovery

Evidence matrix

Evidence boundary

Mitigation underway

Escalation

Retry with bounds and preserve event IDs

`/health/live`

`openapi/events.yaml`