How to document risks against an architecture
Record risks against the parts of the architecture they apply to, and make them visible on the diagram itself.
When this is useful
- A design review needs the known risks stated rather than discovered in the meeting.
- A risk register exists but nobody connects its entries to the architecture.
- You are handing over a system and the risks are the most valuable thing you know.
Before you start
- The architecture on a page, with the components the risks attach to.
Step 1: Record the risk against the component
Attach the risk to the specific component or connector it concerns. A risk recorded against "the platform" is a risk nobody can act on.
Step 2: Let the tool propose the obvious ones
Suggest risks from diagram reads the architecture and proposes risks for you to accept or reject. It is a prompt list, not an assessment — the judgement stays yours.
Arch ▸ Suggest risks from diagram
Step 3: Show them on the diagram
Turn on the risk overlay so the risks appear on the architecture. This is the difference between a register that gets read and one that gets filed.
Arch ▸ Overlays
What happens next
Risks recorded against components feed the wider governance picture, alongside non-functional requirements and the tech debt report.
Example
A single point of failure recorded against a shared database, displayed as an overlay, and raised by a stakeholder in the review without the architect having to introduce it.
Tips
- Write the risk as a consequence, not a condition. "No retry on the nightly file" is a fact; "reconciliation fails silently for a day if the file is late" is a risk.
- Record the risks you have decided to accept as well. An accepted risk that is undocumented becomes a surprise for whoever inherits it.
Limitations
- Suggested risks are proposals derived from the diagram's structure. They cannot know your context.
- The risk and overlay capabilities are separately enabled.