How to use this tool

Architecture Decision Records — Guide

How to create, manage, and export ADRs for your payment infrastructure, and how to use them as audit evidence for PCI DSS compliance.

What is this tool for?

Architecture Decision Records (ADRs) are lightweight documents that capture the rationale behind significant technical decisions. In payment systems, they serve two purposes: they help engineers understand why the architecture is structured as it is, and they provide audit evidence demonstrating that security and compliance decisions were made deliberately.

The tool comes pre-loaded with five PCI DSS-relevant ADRs for common AWS payment infrastructure decisions (KMS key management, SQS webhook processing, VPC network isolation, MFA enforcement, immutable audit logs). Add your own ADRs, update statuses, and export the full set as a Markdown document.

Step-by-step walkthrough

Step 1 — Review pre-loaded ADRs
  1. Five ADRs are pre-loaded covering the most common PCI DSS architecture decisions for AWS.
  2. Click any ADR to expand and read the full context, decision, consequences, and alternatives.
  3. Update the PCI DSS references if your implementation covers different requirement numbers.
Step 2 — Create a new ADR
  1. Click + New ADR to open the creation form.
  2. Fill in all fields — see the field reference below for what each section should contain.
  3. Set the status to Proposed if the decision is still under discussion, or Accepted if it has been approved and implemented.
Step 3 — Export for audit
  1. Click Export Markdown to download all ADRs as a single document.
  2. Share with your QSA as supplementary evidence, or commit it to your infrastructure repository.

ADR fields explained

Each field has a specific purpose in the audit context. Incomplete ADRs — missing context, alternatives, or PCI references — are less useful as compliance evidence.
Title
A short, specific description of the decision. Use the format "Use X for Y" or "Implement X to solve Y". Good: "Use AWS KMS CMKs for PAN encryption". Bad: "Encryption decision".
Status
Proposed (under discussion), Accepted (approved and implemented), Deprecated (superseded by a newer ADR), or Superseded (replaced — add a reference to the new ADR).
Date
The date the decision was accepted. Used for audit trails and to identify whether an ADR pre-dates a specific PCI DSS version.
Deciders
The people or roles who made the decision. For PCI-relevant decisions, this should include the Security Lead or CISO.
PCI DSS Ref
The PCI DSS requirement numbers that this decision addresses or satisfies. Used to map your architecture decisions to compliance controls.
Context
The situation that made this decision necessary. What problem were you solving? What constraints existed? This is read by future engineers trying to understand why the architecture is the way it is.
Decision
The specific choice made. Include enough technical detail that someone can implement it from this document alone.
Consequences
What happens as a result of this decision — both positive (security improvement, compliance control) and negative (added complexity, cost, operational overhead).
Alternatives
Other options that were considered and why they were rejected. Critical for audit trails — QSAs sometimes ask why alternatives were not chosen.

Key terms

ADRArchitecture Decision Record — a short document that captures a significant architectural decision, its context, rationale, and consequences. Originally popularised by Michael Nygard.
Targeted risk analysisA PCI DSS v4.0 concept (Req 12.3.2) where each requirement must be supported by a risk analysis explaining why the chosen approach appropriately addresses the control. ADRs can serve as this documentation.
Superseded ADRAn ADR whose decision has been replaced by a newer decision. The old ADR is kept in the record with Superseded status and a reference to the new ADR, preserving the full decision history.
Decision rationaleThe documented explanation of why a particular approach was chosen over alternatives. QSAs use this to verify that security decisions were deliberate rather than accidental.

Frequently asked questions

Ready to document your architecture decisions?
Review the pre-loaded PCI DSS ADRs, add your own, and export as audit evidence.