Draw the system before choosing an agent

In this note

A customer asks to move a delivery to Friday. The team proposes an agent that reads the message, looks up the order, and changes the date. Before discussing frameworks, I’d ask them to draw what happens if the warehouse has already started packing it.

We need the order record, the dispatch rule, and the person who can approve an exception in the drawing. We also need somewhere to keep a request while it waits. An arrow from “agent” to “order API” leaves those decisions unexplained.

This hypothetical design exercise follows that request through four views: people and records, components, failures, and permissions. You can use the same approach for a refund or onboarding request. Start with one case rather than drawing the whole company.

Write down the result before the components

The customer is signed in to an order portal. Success means the order system records the permitted date change and a separate read confirms that exact operation. Only then can the portal tell the customer the date changed.

Assume customers may change the date before dispatch if a slot is available. After a cutoff, a coordinator must approve the change. We’ll design around those rules here. For a real service, the logistics owner would need to confirm the current policy and how the order system enforces it.

Follow one customer account, one order, and one proposed date. Leave address changes, cancellations, and payments alone. Name the person responsible for the result and the team that handles a stuck request.

First view: people and authoritative records

Draw the customer and coordinator outside the application, with the order system and delivery-slot service beside it. The order system owns the date. The application keeps the request and review evidence; it must not report a new date merely because it saved a proposal.

Sources and owners in the hypothetical delivery-date workflow
Record or actor	Responsibility
Customer portal	Binds the signed-in customer to the permitted order; displays the request’s actual status.
Order system	Owns order identity, customer association, dispatch state, delivery date, revision, and committed operation.
Delivery-slot service	Owns available dates and any reservation required to avoid offering the same capacity twice.
Logistics policy owner	Owns cutoff rules, exceptions, and who may approve them.
Coordinator	Approves or rejects the exact exception with the evidence and time to review it.
Request store	Retains the proposal, source revisions, approval, operation identity, state, and confirmation evidence.

The customer needs somewhere to check progress if approval takes hours. Save a request record that survives a restart, and let the portal show requested, awaiting review, confirmed, or unresolved. A model’s conversation history should not be the only place that status exists.

After a restart, the handler needs to find this customer’s Friday proposal, the order version the coordinator reviewed, and any approval already given. It also needs to know whether an update was attempted and which operation to look up in the order system. Those saved links let it resume the request without asking the model to reconstruct what happened or sending the change again blindly.

Second view: the components doing the work

The portal receives the request. Ordinary application code fetches the permitted order and slots, applies the rules, stores the proposal, and routes any required approval. A language model is optional: it may turn a vague message into a proposed date, but its interpretation still needs a check before use.

System sketch: labeled arrows show reads, proposed interpretation, approval, write, and confirmation. Scroll the sketch sideways on a narrow screen if needed.

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

This sketch follows a request that needs approval. Routine requests can skip the coordinator, but still pass the same update and confirmation checks. The “trusted effect service” is the code allowed to submit the change. It checks current conditions before sending it; neither the model’s interpretation nor a saved proposal grants that permission. The request store keeps the links needed to explain what happened.

A hypothetical operating path. These are responsibilities, not six required services.

Receive the requestPortal and request handler bind the customer, account, order, and requested change.
Read the current evidencePermitted adapters fetch the order revision, dispatch state, policy revision, and available slots.
Form and check a proposalCode checks the date and rules. Optional model interpretation returns a proposal, never a permission grant.
Obtain any required approvalThe request store retains the exact proposal. A coordinator sees its sources, expiry, and consequences.
Authorize and attempt the changeThe effect service rechecks current authority and state, then submits one stable business operation.
Verify and report the resultA fresh read from the order system confirms the exact operation and expected change before the portal reports success.

A date picker may avoid the interpretation problem altogether. If customers still need to send messages, compare a model with that picker or a small parser on the same permitted cases. Check wrong interpretations, review effort, rejected requests, response time, and full cost before keeping the model.

These boxes can live in one application using existing services. They show who does each job, not how many deployments to create. Split them only when access, state, scale, or operating responsibilities justify it.

Third view: state, failure, and recovery

Follow a request as its status changes. It may need clarification, wait for approval, or reach an attempted update. Keep attempted and confirmed separate until the order system supplies proof. Retain rejected and expired requests with their reasons, so you can find out where work stopped.

Failure paths to put in the drawing before implementation
What happens	Required design response
The order or slot source is unavailable	Keep the request unresolved and use the existing support path. Do not invent a current date or availability.
The order changes during review	Invalidate the stale proposal and approval as applicable. Fetch fresh state and obtain a new decision before writing.
A slot disappears before commit	Require reservation or an authoritative atomic availability check. An earlier list of slots cannot guarantee capacity.
The change request times out	Persist an unknown effect. Look up the operation in the order system before retrying or reporting failure.
The workflow process restarts	Resume from the request store, preserving the same operation identity and approval conditions.

At order revision 17, the coordinator reviews a Friday change. Before approval arrives, the warehouse dispatches the order at revision 18. The update code must catch that changed version or dispatch state. Approval of the old proposal cannot make the order undispatched again.

Ask whether the order API can check those conditions and apply the change atomically, meaning no other update can slip between the check and the change. Reading first and writing later leaves a gap. Also check whether the API can find an operation and protect against duplicates. If those capabilities are missing, keep this first build review-only. Saving “already sent” in your own application cannot guarantee the order system applies the change only once.

When checking the result, a matching Friday date is not enough: someone else may have made the same change. Use the order system’s evidence to match your operation to the order, new version, and expected state. If you cannot establish what happened, keep the request unresolved and escalate instead of reporting success.

Fourth view: deployment and trust

Mark where the browser, application, model provider, and source systems meet. The signed-in server must determine which customer and account the request belongs to. An order number typed into a message cannot let the customer read someone else’s order, even if the model repeats it confidently.

Keep credentials in the application’s approved connectors. Send the model only the message and permitted information needed to interpret it. A message telling the model to bypass approval remains customer text; it cannot change the software’s rules. Never give the model a general order-edit credential.

Before submitting an update, software rechecks who is asking, which customer they represent, and whether the current policy and order state permit this change. Any approval must identify the exact proposal, reviewer, expiry, and order state it covered. A different requested date needs a new decision.

Keep enough trace information to tell whether a request failed during interpretation, a rule check, review, the attempted update, or confirmation. Minimize private data and set access and retention limits. Name who gets alerted when requests stay unresolved or the review queue grows beyond what the team can handle.

Test a failure before buying the framework

Give the sketch to someone who did not draw it. Ask them to follow a request from another customer account, an ambiguous Friday, a stale approval, a lost slot, and a timeout after the source commits. They should be able to name the component that stops the request and the record that proves what happened.

Write the expected result beside each path. Another account’s order must stay hidden. A changed order must reject the old proposal. A timeout must not lead to a second operation, and confirmation must wait for source evidence. Later, test those expectations against the real interfaces; the drawing alone cannot establish they work.

Ask the team that will run the service to join the exercise. Who can resume an interrupted request, change a cutoff, check a model replacement, or pause updates? Before release, they also need capacity to review and support the work, plus a tested rollback path. Put those jobs on the plan while the design is still changeable.

Leave the review with a decision someone can revisit

I’d start this delivery service with the portal, ordinary workflow code, existing connectors, and a request record that survives restarts. Add message interpretation only if it beats the simpler input path. Keep actual updates out of scope until the order system can enforce current conditions, approvals, duplicate protection, and confirmation.

Use the worksheet to draw the four views and record your starting choice. Mark which parts you’ve tested and which are still proposals. Pick the first unanswered question about a source system, name who will check it, and resolve that before committing to the build.

Back to notes