Write the Design Down
Module 6 of 7 in the chapter Choosing the Right Integration Design, chapter 16 of the Integration Architect course. Each module stands on its own. Previous: Combining Mechanisms, and Licensing Them · Next: Checkpoint 2: Steve Trucking Under Load
The question this module answers: Once the design is chosen, how do you write it down so that someone else can build it, run it and review it?
A Design Nobody Wrote Down
Section titled “A Design Nobody Wrote Down”Every integration design gets made. The question is whether it gets written down. If it doesn’t, it lives in the head of whoever built it, and it leaves when they do. The next person finds an arrow on a diagram labelled “SMS,” and has to read code to learn who calls whom, with what credential, and what happens when it fails.
You’ve already met the two pieces that fix this. Chapter 5 turned the landscape into an inventory: four answers for every arrow (chapter 5 module 6). And the Data Architect course gave every important arrow a contract: what the data means, who owns it, how fresh, how much (Integration Data Contract). This module puts them together, and adds what Part 2 taught: one record per arrow.
One Record, Two Halves
Section titled “One Record, Two Halves”The landscape is the index. Each important arrow gets a number, and each number opens a record. The record has two halves.
One record per arrow. Every line something you can check.
The data contract comes from the Data Architect course, and I won’t repeat it here: initiator, data direction, freshness, volume and shape, key, write authority, pattern, mechanism, proof of delivery, sensitivity and travel, and change. Its rule holds for the whole record: “A contract line you can’t check is a hope, not a requirement.”
The integration lines are the ones this course adds. The contract’s mechanism line says “the integration architect’s choice.” This half is where the integration architect makes it, and writes down everything it takes:
| Line | The decision | Where the course teaches it |
|---|---|---|
| Mechanism, and why | What carries it, and the trade-off card that chose it | Module 1, module 4 |
| Identity and credential | Which identity calls, with which credential, held where, by whom | Chapter 13 |
| Failure plan | Out: where it’s logged, who’s told, how it’s retried. In: how the other side retries and recovers | Chapter 14 |
| Conductor and undo | If there’s more than one step: who holds the plan, the undo for each step, every wait’s deadline | Chapter 15 |
| Owner and runbook | The team that runs it, the team that owns the outcome, and what each does when it breaks | Chapter 14 module 6 |
| Running cost | What it counts against every day: API calls, event deliveries, licences, another system’s capacity | Module 3, module 5 |
| Last checked | The date every fact in the record was last checked | Module 2 |
Zoom In: The Day-Before Message, Written Down
Section titled “Zoom In: The Day-Before Message, Written Down”Here’s one arrow, end to end. The day-before message was module 1’s open question; module 4 chose option B, a platform event to the integration layer. Now it gets its record.
Zoomed in: one arrow, every line answered.
| Line | The day-before message |
|---|---|
| Pattern | Fire and forget, from Salesforce (chapter 7 module 7) |
| Mechanism, and why | A platform event, “a message is due,” published by Salesforce; the integration layer calls the provider. Why: it keeps every outside call and its retries in one place (module 4) |
| Key | The delivery’s ID, sent to the provider as the message’s own key, so a repeat is recognized |
| Identity and credential | The layer subscribes with its own integration user (chapter 13 module 4). The provider’s key moves out of Salesforce, into the layer’s secret store (chapter 13 module 8) |
| Failure plan, out | The layer logs every call with the delivery’s ID, and retries with the same key (chapter 14 module 4). After an outage, it replays from where it stopped, inside the event bus’s retention (chapter 11 module 4) |
| Failure plan, in | The provider reports what it sent. Requirement for week one: confirm the provider accepts a repeat key, so a retry never sends two texts |
| Conductor and undo | One step, so no conductor. The message is the step that can’t be undone, so it goes last, after the delivery is confirmed for tomorrow (chapter 15 module 5) |
| Owner and runbook | The integration team runs it; customer care owns the outcome. When messages stop, the integration team is told first |
| Running cost | One event published and one delivered per message, against the event allocations (chapter 11 module 5), and the layer’s capacity |
| Last checked | 2026-11-04 |
Notice two things.
The record changed the inventory. Chapter 5’s inventory had the provider’s key in a named credential in Salesforce, owned by customer care. That was the right starting point. The design moved the key to the layer, and split the owner in two: the team that runs it, and the team that owns the outcome. When the design changes, the record changes, the same day. An inventory that disagrees with the design is worse than none, because people trust it.
The record found a requirement. Writing the failure plan down asked a question nobody had asked: will the provider recognize a repeat? If not, a retry sends a second text to the recipient. That’s exactly what writing it down is for: finding architecture work before production finds it for you.
What the Record Is For
Section titled “What the Record Is For”A record like this does three jobs.
- It builds. A developer who’s never met you can build from it.
- It runs. At two in the morning, the person on call knows who owns it, where it’s logged and what to try.
- It reviews. A review stops being “does the diagram look right?” and becomes a check, line by line. Chapter 24 reviews someone else’s design that way.
Test knowledge. Expect to justify a design, not just name it. For each integration, be ready to state the pattern, the mechanism and why, how it authenticates, how errors are handled and retried, and who is notified. A design you can state line by line is a design you can defend.
Beyond the exam: what AI changes. An AI assistant is very good at filling a record like this from a design conversation, a diagram or the code itself. Use it. Then check every line it filled in, because it will fill in an answer for every line, including the ones nobody decided. A blank line is honest. A confident line that nobody chose is the most dangerous thing in the record.
What an Architect Decides Here
Section titled “What an Architect Decides Here”- The index: which arrows on the landscape get a record.
- For each: both halves, the data contract and the integration lines.
- How each line will be checked, and who checks it.
- Who keeps the record current when the design changes, the same day.
Explore
Section titled “Explore”- Integration Data Contract: the Data Architect course, the data half and contract C1.
- The Landscape as an Inventory: chapter 5, the four answers per arrow.
- Every Arrow, Out and In: chapter 14, the failure plan’s questions.