Skip to content

Architecture Decision Records

An Architecture Decision Record (ADR) captures one significant decision: the context, the choice, the alternatives considered and the consequences. ADRs keep the reasoning behind the platform, so later changes are made knowing why things are the way they are.

Status: partly in place

ADRs exist, but they are stored inside individual repositories and there is no central index. This page is that index.

Index

ADR Title Status Where
ADR-0001 MCSB stays audit-only; enforcement lives in separate custom initiatives. It also covers the mandatory tag standard and the audit-to-deny promotion plan. Accepted (2026-08-31) azure-governance-epac/Docs/adr/
ADR-0010 PAG pattern for Entra directory role assignments Proposed azure-governance-azgovviz-analyzer/knowledge/iam/

The numbering has gaps (ADR-0002 to ADR-0009 are not in the repository). Either find and add them, or record that those numbers were never used.

When to write an ADR

Write one when a decision:

  • changes the Security Model, for example a new Lane A exception or a tier reclassification;
  • is expensive to reverse, such as management group structure, network topology or the state storage layout;
  • chooses between real alternatives that people will question later;
  • accepts a risk. Also add it to the Exceptions Register.

Don't write one for routine changes that follow an existing pattern.

Format

Keep each ADR to one page:

# ADR-NNNN: <decision in a short sentence>

## Status
Proposed | Accepted (YYYY-MM-DD) | Superseded by ADR-NNNN

## Context
What forces the decision. Constraints, drivers, current pain.

## Decision
What was decided, in plain terms.

## Alternatives considered
Each option, and why it wasn't chosen.

## Consequences
What becomes easier, what becomes harder, and what must now be done.
  • One numbering sequence across the platform, stored in one place, for example docs/adr/ in a platform repository. Link to it from here.
  • Never edit an accepted ADR's decision. Write a new ADR that supersedes it, and update the old one's status.
  • Link ADRs from the code they govern. The EPAC assignment files already reference ADR-0001 in their header comments. That is a good pattern to repeat.