# System sketch and decision record Use this with the workflow owner and people responsible for the source systems. A drawing is a proposed design, not evidence that its boundaries work. ## Start with these questions 1. Which request starts the work, and which cases qualify? 2. What result must be accepted, and who can independently reject it? 3. Which systems own the facts and any changed business record? 4. Who owns the outcome, technical design, and operation of the service? Record the scope, exclusions, period, and evidence revision beside the sketch. Use the four views below to follow one request, including a failure, through the proposed design. ## Four views 1. People and systems: who starts the request, what triggers it, and where do they work? Which sources may they use, which system must record the result, and who owns each? 2. Components: where does the application save a request while it waits? Which code applies rules, which optional component predicts, retrieves, or interprets, and where does a person review? Show the code allowed to submit a change, the separate result check, and the records used to monitor what happened. 3. Decision and state: what inputs and source versions does each step use? Which status changes are allowed, which rules must remain true, and what result must the destination record? Draw what happens with an unclear request, denied access, a timeout, a restart, or a case that needs help. 4. Deployment and trust: how does each component establish who is asking and which customer's records they may use? Where are credentials kept, where may data be sent, which data is private or restricted, and how long may it be retained? Show how a tested version is released and how the team returns to the previous one. For each arrow, name the information or effect, source owner, current authority, failure response, and evidence that the next step may proceed. A box is a responsibility; it need not be a separate service. ## Completed hypothetical sketch: delivery-date change Status: proposed teaching design. No services deployed, customer data accessed, source API qualified, or business benefit measured. ```text Customer | signed-in request v Portal + request handler |-- READ --> Order / slots / policy |-- ASK ---> Optional interpreter | (proposal only) |-- SAVE --> Request + evidence store | exact proposal v Coordinator | required approval v Trusted effect service | conditional write v Order system | verify operation v Verified request record | confirmed status v Portal ``` The trusted effect service is the code permitted to submit a change. Read and interpretation arrows grant no write permission. Coordinator approval is needed only for the declared exception path. The request store retains the proposal, evidence, approval conditions, and operation; the order system owns the authoritative date and result. Atomic means the source checks the conditions and applies the change as one operation. | Decision | Proposed choice and missing evidence | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accepted outcome | Order system confirms the permitted new date and exact committed operation; portal then reports confirmed. Source verification contract still needs inspection. | | Included work | One signed-in customer, one owned order, one available date change. Address, payment, and cancellation excluded. | | Sources | Order system owns order/customer/revision/dispatch/date; slot service owns availability; logistics owner owns policy. Actual contracts and permissions unverified. | | User surface | Existing order portal shows received, awaiting review, confirmed, rejected, or unresolved. Whether customers can follow these statuses still needs testing. | | Mechanisms | Rules enforce eligibility and cutoff. Date picker is baseline. Optional model interprets vague messages only if a matched comparison justifies it. | | Durable state | Request store preserves the Friday proposal, the order version reviewed, other source versions, approval conditions, and the operation to look up after a restart. Keep attempts, confirmation evidence, and decisions too. Storage and retention still need checking. | | Action boundary | Trusted effect service rechecks current identity, scope, policy, approval, and order state. Source must enforce conditional change and slot availability atomically as appropriate. | | Duplicate / unknown effect | Stable business operation identity; source-enforced duplicate protection and operation lookup before retry. Target support unknown; absent support keeps writes out of scope. | | Fallback | Existing coordinator/support process. Unavailable sources or ambiguous effects remain unresolved rather than confirmed. | | Starting decision | Investigate source contracts and compare picker/parser/model on permitted cases. No write admission until controls and target verification are established. | | Revisit trigger | New action, source API, approval rule, population, interpretation route, or operating constraint. | ## Your decision record - Which design meets the job with the fewest necessary components, and why? ____________________ - Which simpler alternatives did you compare, using what evidence? ____________________ - Which source capabilities remain unknown, and who will investigate them? ____________________ - What may the service read or change, which approvals are required, and what is the maximum tolerable loss? ____________________ - Which current policy applies? How does approval identify the exact change and source state it covers? ____________________ - Which failure scenarios were tested at the target, with what evidence? ____________________ - What are the one-time and recurring costs, and the budget ceiling? ____________________ - How much review and support capacity is confirmed? ____________________ - Which versions work together, which previous version can be restored, and who may pause or roll back the service? ____________________ - Who will run and support the service, and which recovery/support tasks have they practised? ____________________ - What investigation or implementation step is permitted next? ____________________ - Who may decide, by when, using evidence through which cutoff? What would require a new review? ____________________ ## Walk the failure paths - Wrong account: no unauthorized source data or effects. - Ambiguous date: request clarification or review, no guessed write. - Stale order or approval: fresh evidence and decision, no stale effect. - Lost slot: authoritative reservation or conditional availability, no double promise. - Timeout after commit: reconcile the stable operation before retrying. - Restart: resume durable state with the same operation and still-current conditions. - Source cannot prove the operation: unresolved effect and escalation, not completion. Use real source contracts, safe test seams, and representative cases before a release decision. This worksheet does not approve production or certify safety, compliance, correctness, or value. Caisi - David Ahmann - Created 12 October 2026