Governance artifact
Architecture Decision Register
Decisions are recorded with the context that produced them, the alternatives rejected, and the cost accepted. A decision without a stated tradeoff is an opinion, not an architecture decision.
Summary
Decision register
| ID | Decision | Case study | Status | Reason | Major tradeoff | Operational consequence |
|---|---|---|---|---|---|---|
| ADR-001 | Managed database service vs self-managed database | Secure Cloud Migration | Accepted | Small operations team cannot sustain database maintenance and recovery obligations. | Reduced low-level control and higher unit cost. | Upgrade windows follow provider timelines; tuning is limited to engine parameters. |
| ADR-002 | Multi-zone availability vs single-zone deployment | Secure Cloud Migration | Accepted | The 99.9% objective is not defensible with a single-zone design. | Materially higher data-tier and cross-zone traffic spend, plus added write latency. | Zone-failure drills become a recurring operational commitment. |
| ADR-003 | Private application services vs public exposure | Secure Cloud Migration | Accepted | Public exposure of compute is unnecessary risk when ingress can be centralized. | Higher network complexity and troubleshooting friction. | All access paths must be explicitly designed, including break-fix support. |
| ADR-004 | Managed secrets service vs application configuration files | Secure Cloud Migration | Accepted | Configuration-file credentials cannot be rotated or audited reliably. | A new runtime dependency in the critical path. | Secrets-service availability becomes an application availability factor. |
| ADR-005 | Centralized identity provider as the primary control plane | Zero-Trust Enterprise Access | Accepted | Only a central identity plane makes least privilege and revocation reliable. | Single dependency with organization-wide blast radius. | Identity outage handling and break-glass drills become mandatory. |
| ADR-006 | Just-in-time privileged access vs standing administrative rights | Zero-Trust Enterprise Access | Accepted | Standing privilege is the highest-value target in the estate. | Administrative speed traded for containment. | Elevation and break-glass paths must be drilled on an illustrative quarterly cadence; JIT reduces but does not eliminate privileged-account risk. |
| ADR-007 | Workload identity federation vs shared static service credentials | Zero-Trust Enterprise Access | Accepted | Shared static keys defeat least privilege and attribution. | Application change effort and less obvious failure modes. | Token issuance health becomes an availability dependency. |
| ADR-008 | Warm cross-region standby vs active-active multi-region | Resilient Data & Application Platform | Accepted | Cost and complexity of active-active are not justified at current revenue exposure. | Longer target recovery time, an accepted data-loss window, and partly idle standby cost. | Regional failover remains a rehearsed human decision. |
| ADR-009 | Graceful degradation via feature flags vs hard dependency failure | Resilient Data & Application Platform | Accepted | Total outage from one non-critical dependency is disproportionate. | Additional complexity and test surface. | Flag state becomes part of change control and incident review. |
| ADR-010 | Illustrative monthly timed restore testing vs backup-success monitoring only | Resilient Data & Application Platform | Accepted | An untested backup is not a recovery capability. | Recurring cost and maintenance of test automation. | Restore time becomes a tracked service metric with an owner. |
Detail
Full records
ADR-001
Managed database service vs self-managed database
AcceptedSecure Cloud Migration- Context
- The legacy system runs a self-managed database on end-of-life hardware with manual backups and no failover. The operations team is small and has no dedicated database administrator.
- Decision
- Adopt a managed relational database service with automated backups, patching, and a synchronous standby.
- Alternatives considered
- Self-managed database on cloud virtual machines
- Lift-and-shift of the existing database host
- Refactor to a distributed database engine
- Benefits
- Removes patching and backup toil from a small team
- Failover and point-in-time recovery are platform features
- Recovery point objective of 15 minutes achievable without custom tooling
- Tradeoffs
- Higher per-hour cost than raw compute
- Limited operating-system and engine-level tuning
- Version upgrade timing partly dictated by the provider
- Operational impact
- Operations shifts from database maintenance to monitoring and query performance work; runbooks reference platform failover rather than manual recovery.
ADR-002
Multi-zone availability vs single-zone deployment
AcceptedSecure Cloud Migration- Context
- The availability objective is 99.9% with a 4-hour recovery time. A single-zone deployment is cheaper but exposes the application to a full outage from one facility event.
- Decision
- Deploy application and data tiers across three availability zones with a synchronous database standby.
- Alternatives considered
- Single-zone deployment with restore-from-backup recovery
- Two-zone deployment with asynchronous replication
- Cross-region active-active
- Benefits
- The design is intended to maintain service through a single availability-zone failure, subject to application, dependency, and failover health
- Maintenance can be performed zone by zone
- Supports the stated recovery objectives without heroics
- Tradeoffs
- Multi-zone redundancy materially increases data-tier infrastructure and cross-zone traffic cost
- Cross-zone traffic adds write latency and network charges
- More complex capacity planning
- Operational impact
- Deployment and load testing must account for zone-aware routing; failover must be exercised through game days and recovery testing to remain credible.
ADR-003
Private application services vs public exposure
AcceptedSecure Cloud Migration- Context
- The legacy application was reachable from a flat internal network. In the target design, compute could be placed in public subnets for simplicity or kept private behind the load balancer.
- Decision
- Place application and data tiers in private subnets; only the edge and load balancer are internet-facing, with private endpoints for platform services.
- Alternatives considered
- Public subnets with host firewalls
- Public compute restricted by IP allow-lists
- VPN-only access to all tiers
- Benefits
- Reduces direct internet exposure of compute and data rather than relying on host-level defenses alone
- Forces traffic through inspected, logged ingress
- Simplifies evidence for boundary control reviews
- Tradeoffs
- More network design and troubleshooting effort
- Requires deliberate patterns for egress and administrative access
- Slightly slower initial developer onboarding
- Operational impact
- Support access happens through identity-brokered sessions rather than direct connections; egress must be explicitly designed for updates and third-party calls.
ADR-004
Managed secrets service vs application configuration files
AcceptedSecure Cloud Migration- Context
- Credentials are currently stored in configuration files on application hosts, are rarely rotated, and are copied between environments.
- Decision
- Retrieve all credentials at runtime from a managed secrets service with per-environment scoping and scheduled rotation.
- Alternatives considered
- Encrypted configuration files with a deployment-time key
- Environment variables injected by the pipeline
- Self-hosted secrets manager
- Benefits
- The target design keeps application credentials out of source control and container/application images
- Rotation becomes a routine operation instead of a project
- Access to secrets is authorized and audited per identity
- Tradeoffs
- Introduces a runtime dependency on the secrets service
- Adds cold-start latency on credential retrieval
- Requires caching and failure handling in application code
- Operational impact
- Applications need retry and cache logic; incident runbooks must cover secrets-service degradation.
ADR-005
Centralized identity provider as the primary control plane
AcceptedZero-Trust Enterprise Access- Context
- Access is currently granted by network position and per-application local accounts, leaving no consolidated view of entitlements.
- Decision
- Make one workforce identity provider authoritative for workforce authentication, with a policy layer evaluating authorization for applicable protected-resource requests.
- Alternatives considered
- Keep per-application authentication with a password manager
- Network-centric access via expanded VPN segmentation
- Federated multi-provider model per business unit
- Benefits
- One place to enforce MFA, review access, and revoke on exit
- Consistent telemetry for every authentication decision
- Enables conditional access based on device and risk signals
- Tradeoffs
- Concentrated dependency on a single platform
- Migration effort for legacy header-based applications
- Policy misconfiguration has broad blast radius
- Operational impact
- Identity availability becomes a top-tier dependency; policy changes require staged rollout and report-only testing.
ADR-006
Just-in-time privileged access vs standing administrative rights
AcceptedZero-Trust Enterprise Access- Context
- Administrators currently hold permanent privileged roles on their daily-use accounts, so any endpoint compromise is immediately a privileged compromise.
- Decision
- Introduce separate administrative identities with approval-gated, time-bound elevation and session recording; retain two governed break-glass accounts.
- Alternatives considered
- Standing admin rights with stronger monitoring
- Shared privileged accounts held in a vault
- Full separation with permanently privileged admin identities
- Benefits
- Removes standing privilege from everyday endpoints
- Creates an approval and session trail for sensitive work
- Limits the value of a stolen administrator session
- Tradeoffs
- Slower emergency response if elevation is unavailable
- Approval workflow adds process overhead
- Break-glass accounts need their own governance and testing
- Operational impact
- On-call procedures must include elevation steps; break-glass use is alarmed and reviewed after every activation.
ADR-007
Workload identity federation vs shared static service credentials
AcceptedZero-Trust Enterprise Access- Context
- Service-to-service calls use long-lived shared keys copied across environments, with no reliable rotation or attribution.
- Decision
- Use federated workload identities that exchange platform-issued tokens for short-lived, scoped credentials.
- Alternatives considered
- Long-lived keys with scheduled rotation
- Mutual TLS with a private certificate authority only
- Per-environment keys held in the secrets service
- Benefits
- Reduces reliance on long-lived shared service secrets stored in application images or hosts
- Workload-specific identities enable stronger attribution of authenticated service calls when supported by platform telemetry
- Scoped permissions per service instead of one shared key
- Tradeoffs
- Requires application changes and a credential-refresh path
- Debugging authentication failures is less obvious
- Depends on platform token issuance being healthy
- Operational impact
- Teams must instrument token-refresh failures; incident runbooks include identity-issuance troubleshooting.
ADR-008
Warm cross-region standby vs active-active multi-region
AcceptedResilient Data & Application Platform- Context
- The platform must survive a regional failure, but active-active operation would require data-conflict handling and roughly double the run-rate.
- Decision
- Run multi-zone active in the primary region with an asynchronously replicated warm standby region promoted through an approved runbook.
- Alternatives considered
- Active-active across two regions
- Backup-and-restore only recovery
- Pilot-light region rebuilt on demand
- Benefits
- Designed around an illustrative 4-hour cross-region RTO target at moderate cost
- Avoids multi-region write-conflict complexity
- Keeps the everyday operating model simple
- Tradeoffs
- The illustrative asynchronous-replication design accepts an RPO target of up to one hour for a regional disaster scenario
- Recovery depends on human declaration and runbook quality
- Standby capacity is partly idle spend
- Operational impact
- An illustrative quarterly promotion-drill cadence is modeled to exercise the recovery runbook; the accepted data-loss window must be communicated to the business in advance.
ADR-009
Graceful degradation via feature flags vs hard dependency failure
AcceptedResilient Data & Application Platform- Context
- A third-party payment dependency has no alternative provider, and today its failure takes down unrelated customer journeys.
- Decision
- Introduce degradation flags and durable queueing so non-critical features disable independently while core journeys continue in a reduced mode.
- Alternatives considered
- Fail the whole request when any dependency is unavailable
- Add a second payment provider now
- Synchronous retries with longer timeouts
- Benefits
- Core journeys survive selected dependency outages, including loss of the non-authoritative cache tier, which is bypassed or served in reduced mode
- Queued work replays after recovery rather than being lost
- Clearer customer communication during partial outages
- Tradeoffs
- More application state and flag configuration to maintain
- Reduced-mode behaviour must be tested like a real feature
- Risk of flags being left in the wrong position
- Degradation is only valid where the business journey and data-integrity requirements allow it; some dependency failures must still fail closed
- Operational impact
- Flag state must be visible in dashboards and reviewed after every incident; degraded modes need their own test coverage.
ADR-010
Illustrative monthly timed restore testing vs backup-success monitoring only
AcceptedResilient Data & Application Platform- Context
- Backups complete successfully but no restore has been timed, so the recovery time objective is an assumption rather than a measurement.
- Decision
- Run an illustrative monthly automated restore into an isolated environment and record the restore duration.
- Alternatives considered
- Rely on backup job success metrics
- Annual manual restore exercise
- Continuous restore validation on every backup
- Benefits
- Timed restore exercises provide measured evidence that can be compared with the stated recovery objective
- Restore exercises can surface backup-integrity problems, restore failures, or procedural gaps that backup-success monitoring alone may not reveal
- Provides illustrative evidence for stakeholders reviewing recovery readiness
- Tradeoffs
- Ongoing compute cost for the restore environment
- Engineering time to maintain the automation
- Test window constrained to out-of-hours
- A successful restore test validates the tested restore path under the exercise conditions; it does not by itself prove full application disaster-recovery readiness
- Operational impact
- Restore duration is tracked as an operational metric; regressions raise a risk-register update.