How to document non-functional requirements in an architecture
Record non-functional requirements against the components they constrain, and use the tech debt report to see where the architecture is not meeting them.
When this is useful
- The NFRs exist but live in a document nobody opens during design.
- A design is being reviewed against availability, performance or security expectations.
- You need to show where the architecture is knowingly carrying debt.
Before you start
- The architecture modelled, and the NFRs themselves — stated as something checkable rather than as an aspiration.
Step 1: Attach the requirement to what it constrains
An NFR recorded against the component it applies to is reviewable; the same sentence in a requirements document is not. This is the whole point of the step.
Step 2: State it in checkable terms
"Responds within 200ms at the 95th percentile under 500 concurrent users" can be assessed. "Must be fast" cannot, and will be quietly ignored by everyone downstream.
Step 3: Read the tech debt report
The Tech Debt Report reads the recorded content to show where the architecture is carrying debt against its stated requirements.
Arch ▸ Tech Debt Report
What happens next
NFRs recorded against components give simulation something to test against — a resilience or bottleneck result is only meaningful relative to a stated requirement.
Example
An availability requirement recorded against a payment path, which made a single-region dependency visible as debt rather than as an implementation detail.
Tips
- Record the NFRs you are not meeting. A requirement with a known gap is manageable; an unstated one is not.
- Attach them during design. An NFR added after build is a complaint, not a requirement.
Limitations
- The report reflects what has been recorded. It does not measure a running system.
- NFR and tech debt capabilities are separately enabled.