Architecture & Technical Design · master area
Security Architecture
Threat modelling, auth design, data protection. Re-read at every Epic that touches authorisation or PII. Security selected as an ility, designed into the system, verified at every layer — not bolted on at audit time.
Owners: Tech Lead, Security Phase it lives in: What We Build → How We Build The corpus principle this enacts: UX/product ilities are first-class requirements — security is the most expensive ility to bolt on later.
Where it lives in the chain
- What We Build · Ilities selection — where security is selected as a target
- How We Build · Testing · QA craft — where it's verified
How to do this
The security ADR names, for every Epic that touches sensitive data or operations:
- Threats — who is the adversary, what are they trying to do, what's the entry point? Three or four named threats, not an abstract list.
- AuthN — how does the request prove it's from who it says? Token shape, expiry, refresh, revocation.
- AuthZ — what does the principal have permission to do? Resource-level, not just role-level. Tested in unit tests, not just integration.
- Data protection — what's encrypted at rest, at transit, in logs? What's PII; what's not.
- Audit — what's logged, who can read the logs, retention.
- Failure mode — if auth fails, what does the user see? The error message that doesn't leak ("login failed" not "user not found").
What good practice looks like
The JWT outage is the cautionary tale. A six-line XML change to the API gateway locked out 12,400 users — because the gateway required a claim tokens didn't have. The chain-aware label was integration-gap; the operational label was configuration. The fix was a token-compatibility smoke test in the pipeline. The lesson: changes to authentication, authorisation, or session handling deserve the same pipeline rigour as application code — and a contract test against existing tokens.
Security architecture is lived discipline, not a quarterly threat-model meeting. Every Epic that touches auth or PII triggers a re-read. The re-read takes 20 minutes; the absence costs hours of incident.
Related crafts
- Security Testing (SAST) — verification
- Secrets Management — operational side
- Ilities Selection — where security is named