Draw a system boundary from one real user journey

A system diagram can contain every database and service while still failing to explain who is responsible when a user sees the wrong result. The missing information is often the journey: what action starts the work, which decisions authorize it, where durable state changes, and which outcome counts as success. Drawing from infrastructure first encourages boxes with vague arrows. Drawing from an observable user outcome exposes the contracts that actually matter.

Consider an illustrative application where an organization administrator invites a colleague. The invitation must belong to the administrator's organization, email delivery may be delayed, and acceptance must not grant access to a different tenant. This example is a design exercise, not a report of an implemented system. It gives each boundary a concrete reason to exist.

Write the outcome before drawing boxes

Describe the happy path in a few sentences. An authenticated administrator enters an email address. The server checks invitation permission, stores an invitation for that organization, and schedules a notification. The recipient accepts a valid invitation and becomes a member of the same organization. The UI shows whether the invitation exists and whether delivery is pending or failed.

Now write the negative outcomes. A member without invitation permission cannot create one. A provider timeout must not make a durable invitation disappear. An expired invitation cannot grant membership. Repeated submissions should have a defined duplicate policy. These statements identify responsibilities more effectively than a diagram labeled frontend, backend, and database. They also reveal ambiguous product requirements before implementation spreads them across several layers.

Follow identity through the journey

Start the trace at the authenticated request, not at the visible button. Record how the server obtains the actor's identity and organization membership. A browser-supplied organization ID can identify a requested context, but it cannot prove authorization. The server must verify that the actor can invite someone within that context.

Mark where identity changes form. A session cookie becomes an authenticated account; membership becomes a permission decision; an invitation token later becomes evidence of an allowed acceptance operation. Each conversion has a trust boundary. The token should identify an invitation record whose state the server validates. Do not let a hidden UI field become the authority for the eventual organization. This tracing also identifies where public error messages and private diagnostic details need different treatment.

Inventory contracts and data owners

For every arrow, write a verb and the relevant contract. The browser submits an invitation request. The application stores invitation intent. A worker sends an email. The provider returns an acceptance or delivery status. A recipient redeems an invitation. Avoid arrows labeled data or integration because they conceal direction and failure semantics.

Assign ownership to records. Invitation logic owns expiration and redemption state. Membership logic owns role assignment. Notification logic owns delivery attempts and provider identifiers. These can be modules in one deployment; a logical responsibility does not demand a service. Note which component may change each state and which components only observe it. The result should help a developer find the rule and help an operator identify the failing dependency, without requiring a diagram for every internal function.

Draw two views at different distances

Create a context view showing people, the application, and the external email provider. Explain what the application does in user terms. Then create a journey view with the request handler, invitation operation, storage, worker, and provider. Keep the levels separate so a product stakeholder can understand the first view without reading deployment details.

Use a plain text artifact if diagram tooling would delay the work. Write a numbered sequence with actor, input, permission check, state transition, output, and failure for each step. Include an explicit boundary between the application and provider. A useful diagram does not need decorative icons. It needs named responsibilities, arrow direction, and a legend explaining whether arrows represent synchronous calls, durable work, or responses. Date it and connect it to the route or module it describes.

Expose partial success

The journey reveals that invitation creation and email delivery are different events. Define the server response accordingly. If the invitation is committed and notification is queued, the response should communicate that state instead of claiming that an email arrived. If creation fails before persistence, the UI should allow correction or retry without showing a nonexistent invitation.

Give retry behavior its own line in the journey. What happens when the browser loses the response after a successful commit? What happens when the worker crashes after the provider accepts a message? A design may tolerate duplicate invitation emails while preventing duplicate membership changes. These are business choices. Use background job design when delivery moves outside the request, and do not hide its eventual state behind an unconditional success toast.

Verify the boundary with evidence

Compare the diagram to an actual route, permission check, persistence operation, and provider adapter. If the implementation does not exist yet, label those components as proposed. If it exists, link the diagram to the relevant files or tests. A diagram that describes an intended permission check while the route omits it is a useful discovery, not proof of safety.

Test the journey's outcomes with synthetic identities. Include an administrator in organization A, a normal member in A, and an administrator in B. Attempt cross-organization invitation creation and redemption with each relevant role. Simulate notification unavailability and confirm that the invitation state remains understandable. Inspect responses and durable state, not only the page. Keep the results attached to the journey so future reviewers know what was actually checked.

Keep the model small and current

One journey cannot prove every boundary in an application. Billing, exports, account recovery, and administration may introduce different authorities or external systems. Start with a representative or risky journey, then add views only when they reveal distinct behavior. Resist expanding the drawing into an exhaustive inventory of classes; that makes updates expensive and obscures the user outcome.

Update the journey when a responsibility moves, a contract changes, or a new failure state appears. Cosmetic file rearrangements usually do not require a redraw. A good maintenance trigger is a pull request that changes who authorizes an operation or who owns durable state. The model remains valuable because it supports concrete change review rather than serving as a one-time presentation artifact.

Ask AI for missing boundaries

Give the assistant the journey description and bounded code context. Ask it to trace each step with file evidence, distinguish proposed components from implemented ones, and list unanswered questions. Useful output includes a table of actor, authority, operation, state change, and failure outcome. Reject explanations that infer behavior from folder names alone.

Then ask for counterexamples: a replayed token, an organization switch during submission, a provider timeout, and a duplicate request. Review whether the existing sequence handles them. Keep credentials and real invitation tokens out of the prompt. An assistant can draft the diagram and find mismatches, but the team must resolve policy decisions and verify execution. This method makes AI architecture help concrete enough to challenge rather than impressive enough to trust.

Sources

The C4 system context documentation explains the external perspective used for the first view.

OWASP's authorization guidance supports reviewing authorization at request boundaries. The invitation sequence is an original illustrative example.