Make an Architecture Decision and See It Built

This walkthrough takes one change from a sketch to a confirmed change in the code. The systems it touches are drawn on the board and its reach is read before anyone agrees. The decision is recorded with the options weighed, the work is handed off and claimed from the repository, and the next sync confirms it. It runs as the playbook Make an architecture decision and see it built (Playbooks). The site's page for the same job is Assess the impact of a proposed architecture change.

The example is Online store, a demo workspace of three apps from the eShop sample, each bound to its own repository: Web Shop, Catalog Service and Ordering Service. The change: the Ordering API sends the customer's "your order has shipped" email inline, from the handler that marks the order shipped. The decision moves that email into a new Order Notifications worker that subscribes to the shipped event on the RabbitMQ event bus. A slow or failing mail provider then never holds an order. The whole run took about an hour, most of it reading.

Before you start

• An app board bound to its repository and synced, so its contracts are adopted. Reach is read from adopted endpoints, events and tables; an app whose contracts have not been adopted shows no consumers.
• An editor role, to draw, commit, publish and hand off.
• The code plugin installed where the developer works, signed in to the app's board (The Code Plugin).

Start the run

Open More playbooks in the sidebar and choose Make an architecture decision and see it built. The guide opens with ten steps in three stages: Draw the change, Decide, Build.

Draw the change where it lands

Right-click the canvas, open Nodes and choose an archetype; the worker became a microservice node. Select it, choose Edit Name in the inspector and name it Order Notifications. Save the board.

On an app board the code owns the structure, so a new node is not saved as fact: it becomes an uncommitted change in your working copy. Click the uncommitted changes pill in the top bar, review it, and choose Commit….

Give the commit a title and a summary, the way you would a commit message. The summary becomes the work item's description. Filed under shows the run's epic and Counts toward the run's step, both already chosen. Leave Release the plan for pickup off. You hand the work item off later, once the decision is agreed. Commit.

The step reads completed, the node stays on the canvas, and the app hub's attention queue shows the new draft, Order shipped notifications move to a worker, awaiting approval.

Read what it reaches

Before deciding, read the change's reach. The worker will subscribe to the event bus, so right-click RabbitMQ Event Bus, point to Dependencies and choose Impact.

Expand

Twenty-two elements depend on the bus across four systems, within three hops. Fourteen are reached only through rows the diagram does not draw: endpoints and channels the code proves. Two hops out sits the Web Shop, in another repository: the consumer a hand-drawn diagram would not have named. Here it is unaffected: the shipped event already exists and the Web Shop does not consume it. The point is that the question was answered from the code, not from memory. Dependencies covers the three questions and their scope.

Decide together

The Decide stage has four steps: record the decision, publish the change for review, the engineering lead agrees, product has read it.

Record the decision

The guide's Draw it in chat opens chat with a prompt for a decision record. On this run chat read the board and reviewed the decision well. Then it said it had no tools to write a decision board in that conversation, at the tree scope or at the board's. That is a product problem, recorded in docs/ux-findings/usecase_change_impact.md. Until it is fixed, record the decision as a Decision work item instead; it carries the same parts.

On the app hub choose Create work item. Name it, choose the Decision type, write the one-line summary, and open Why. The Why holds the context, the decision, the options weighed with the reason each was rejected, the consequences, and what is out of scope:

Options weighed. Keep it inline in the API's domain event handler: rejected, it keeps the provider on the request path. A worker subscribed to the shipped event: chosen. An outbox table polled by a job: rejected, the bus already gives at-least-once delivery and a second table with a poller would duplicate it.

File it under the epic, then add the elements it concerns under Add elements: Order Notifications, RabbitMQ Event Bus, Ordering API. Each anchor asks What should happen to it; choose an answer and write the one line the implementer reads. The editor counts the anchors still unexplained until every one has its note.

Expand

Back on the guide, mark the record step done.

Publish and acknowledge

Open the Board menu and choose Publish this board…. Give it a title, choose Unlisted under access, and publish. The step ticks on its own once the board is live. The next step names the person who has to agree: The engineering lead agrees offers Copy link, for sending the published board, and Confirm. On confirming, the step reads Acknowledged. Product has read it is skippable and stays open until product confirms.

Hand it off

Hand both work items off: the decision from the editor's Hand off to Dev, and the commit's work item from the attention queue's Hand off to Dev. Each becomes Open: locked, and visible to the developers' pulls. The guide's Build stage counts the decision once it is handed off.

Build it

The developer works in the ordering repository with the code plugin.

See it built

On the Work items screen the structural work item reads Completed, with ✓ confirmed by sync and the day. Nobody resolved it: the sync found a node with the proposed name in the code and closed it. The decision work item is closed by hand against that proof, with a note.

Expand

Run /changes in the repository to record the week, and open the board's Changes tab. The week's entry, Order-shipped email moves to a notifications worker, says what the work did and where it landed. It names the Structure rule's answer, four elements added and one changed, and the work item it carried out. Opening it reads who depends on the app and what the change reaches today.

Expand

The run ends on its proof, the confirmed work item, and the playbook returns to the start.

Check it worked

• The node is on the app board and owned by the code: its inspector no longer shows it as changed this session.
• On Work items, the structural work item is Completed with the ✓ and the sync's date; the decision work item is closed with its note.
• The published board opens from its link, read-only, with the worker on it.
• The Changes tab has the week's entry naming the work item.

What's next