Skip to content

Architectural Decision Records (ADRs)

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architectural Decision Record (ADR) captures a single AD and its rationale.

For more information see

Start Here

New to this project? These ADRs cover the foundational design decisions:

  1. ADR-0001: Why Terraform with Azure Developer CLI (azd) is the IaC toolchain
  2. ADR-0002: Why AKS Automatic is the deployment target
  3. ADR-0003: How infra, platform, and software layers are isolated
  4. ADR-0004: How Helm postrender + Kustomize achieves safeguards compliance
  5. ADR-0007: Why deployments use a two-phase gate for Azure Policy convergence
  6. ADR-0017: How namespaces isolate foundation, platform, and service workloads
  7. ADR-0020: Why privileged Azure access bootstrap lives in a separate Terraform state

How to Create an ADR

  1. Copy adr-template.md to NNNN-title-with-dashes.md, where NNNN indicates the next number in sequence.
  2. Check for existing PR's to make sure you use the correct sequence number.
  3. There is also a short form template adr-short-template.md for smaller decisions.
  4. Edit NNNN-title-with-dashes.md.
  5. Status must initially be proposed
  6. List deciders who will sign off on the decision
  7. List people who were consulted or informed about the decision
  8. For each option, list the good, neutral, and bad aspects of each considered alternative.
  9. Share your PR with the deciders and other interested parties.
  10. The status must be updated to accepted once a decision is agreed and the date must also be updated.
  11. Decisions can be changed later and superseded by a new ADR.

When to Create an ADR

Create ADRs for:

  • Architecture patterns (tool registration, dependency injection, callbacks)
  • Technology choices (framework selection, library decisions)
  • Design patterns (component interaction, abstraction layers)
  • API designs (public interfaces, method signatures, response formats)
  • Naming conventions (class names, module structure, terminology)
  • Testing strategies (test organization, mocking patterns, coverage targets)
  • Performance trade-offs (caching strategies, optimization choices)
  • Security decisions (authentication methods, data handling)

Rule of thumb: If the decision could be made differently and the alternative would be reasonable, document it with an ADR.

Templates

ADR Index

Superseded ADRs

Superseded ADRs are kept for historical context. The replacement ADR is linked in the Status column.

Deployment Architecture

ADR Title Status
0001 Use Terraform with Azure Developer CLI (azd) Accepted
0002 Use AKS Automatic as deployment target Accepted
0003 Three-layer deployment architecture Accepted
0007 Two-phase deployment gate for Azure Policy convergence Accepted
0017 Consolidated namespace architecture Accepted
0018 Stack file layout reorganization Accepted
0019 Group feature flags with cascading locals Accepted
0020 Split access bootstrap from core infrastructure Accepted

Runtime & Security

ADR Title Status
0008 ECK self-signed TLS for Elasticsearch Accepted
0009 Selective Istio sidecar injection due to AKS constraints Accepted
0010 Workload Identity for cross-subscription DNS management Accepted
0011 UniqueServiceSelector compliance via label differentiation Accepted

Platform Components

ADR Title Status
0004 Helm postrender with kustomize for safeguards compliance Accepted
0005 Raw Kubernetes manifests for RabbitMQ Accepted
0006 Karpenter NodePools for stateful workload scheduling Accepted
0012 KubernetesExecutor for Airflow with NAP task pod scaling Accepted
0016 Raw Kubernetes manifests for Keycloak Accepted

Service Patterns

ADR Title Status
0013 Use CIMPL chart default images over explicit overrides Accepted
0014 ROSA alignment with deliberate AKS differences Accepted
0015 Reusable OSDU service module and SQL template extraction Accepted