Architecture Decision Records for AWS Integrations
Six months from now, nobody remembers why you chose DynamoDB over Aurora for this service.
//
Busque em todas as páginas da documentação
Six months from now, nobody remembers why you chose DynamoDB over Aurora for this service.
The engineer who made the call has moved teams, the ticket is closed, and the only trace left is the code itself, which shows what was built but not why. An Architecture Decision Record (ADR) is a short, permanent document that captures the reasoning behind a significant, hard-to-reverse decision at the time it is made - so the next person (often you) does not have to reverse-engineer it later or accidentally re-litigate a decision that was already carefully considered.
0001-, 0002-, ...).A lightweight ADR has four sections. Keep each one to a few sentences; an ADR is a decision record, not a design document.
# ADR NNNN: <short, decision-oriented title>
Status: Proposed | Accepted | Superseded by ADR NNNN
Date: YYYY-MM-DD
## Context
What is the situation that requires a decision? What forces - technical,
organizational, cost - are in play? State the problem neutrally, before
the decision, so a future reader can judge whether those forces still hold.
## Decision
What did we decide, stated as a single clear sentence? Follow with the
key facts that made this the right call given the Context above.
## Consequences
What becomes easier? What becomes harder? What did we accept as a
trade-off? Be honest about the downsides, not just the upsides.
## Alternatives Considered
- <Alternative A> - why it was not chosen
- <Alternative B> - why it was not chosenA filled-in ADR for choosing DynamoDB over Aurora for a specific workload - the kind of decision this section's other pages (idempotent design, multi-account architecture) assume has already been made.
# ADR 0007: Use DynamoDB for the Order Event Store
Status: Accepted
Date: 2026-03-14
## Context
The order service needs to store an append-only stream of order events
at a write rate that spikes 20x during flash sales, with strict
per-order-id ordering but no cross-order transactional requirements or
complex joins. The team already runs DynamoDB elsewhere and has
production experience with it.
## Decision
Use DynamoDB, with order_id as the partition key and an event
sequence number as the sort key, on-demand capacity mode to absorb
sale-day spikes without manual capacity planning.
## Consequences
Easier: near-unlimited write throughput during spikes without
provisioning ahead of time; single-digit-millisecond reads by
order_id; no connection-pool management the way a relational
database would require under this load.
Harder: no ad hoc cross-order SQL queries - reporting needs a
separate export path (e.g. DynamoDB Streams to S3); the team must
apply the conditional-write idempotency pattern explicitly, since
DynamoDB does not provide multi-row transactions across order_ids
by default.
## Alternatives Considered
- Aurora (PostgreSQL) - would give SQL flexibility and joins, but
requires provisioning ahead of flash-sale spikes and connection
pooling under load; rejected for this specific write pattern.
- Aurora Serverless v2 - reduces the provisioning problem but still
adds relational connection-management overhead this workload does
not need; revisit if cross-order queries become a hard requirement.# ADR 0012: Single-Region Deployment with a Cold Standby
Status: Accepted
Date: 2026-01-09
## Context
The service has no regulatory requirement for multi-region active-active
operation, and the business's stated tolerance is a few hours of
downtime during a full regional outage, not zero. Multi-region
active-active adds real ongoing cost and operational complexity
(cross-region replication lag, conflict resolution, doubled
infrastructure).
## Decision
Deploy to a single primary region (us-east-1) with infrastructure as
code that can stand up a cold standby in a second region (us-west-2)
within the agreed recovery time.
## Consequences
Easier: no cross-region replication lag to reason about day to day;
lower steady-state infrastructure cost; simpler consistency model.
Harder: a full regional outage requires a manual (though rehearsed)
failover, with a recovery time measured in hours rather than being
instant; the standby region needs periodic drills to stay trustworthy.
## Alternatives Considered
- Multi-region active-active - meets a zero-downtime bar the business
did not actually require, at meaningfully higher cost and complexity.
- No standby at all - cheaper still, but leaves no path to recovery
from a full regional outage; rejected as too great a risk for a
revenue-generating service.Keep the Context section neutral and factual - describe the forces at play before revealing the decision, so a future reader can independently judge whether the reasoning still holds if circumstances change. State the Decision as one clear sentence; if you cannot compress it to one sentence, the decision itself may not be settled yet. Be genuinely honest in Consequences about what gets harder, not just what gets easier - an ADR that only lists benefits is marketing, not a decision record. List Alternatives Considered even when the final choice feels obvious in hindsight, because the reasoning for rejecting them is often exactly what the next person needs when circumstances shift and they are tempted to revisit the decision.
An ADR is immutable once accepted. If circumstances change and the decision needs to be revisited, write a new ADR, mark the old one's status as "Superseded by ADR NNNN," and link between them. This preserves the history of why the architecture evolved, which a single continuously-edited document would lose.
A short, permanent document capturing the context, decision, consequences, and rejected alternatives for a significant, hard-to-reverse architectural choice - written at the time the decision is made.
Ones that are expensive to reverse: service choice (DynamoDB vs Aurora), region strategy, account structure, or a major API contract change. Routine implementation details generally do not need one.
As plain files in the same repository as the code they govern, numbered sequentially, so they are versioned alongside the system and easy to find in context.
No. If the decision needs to change, write a new ADR that supersedes the old one and mark the old one's status accordingly. This preserves the decision history instead of erasing it.
Short - a few sentences per section. An ADR records a decision and its reasoning, it is not a full design document or implementation guide.
Whoever is making or driving the decision, ideally with input from anyone the decision materially affects, written at decision time rather than reconstructed later.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última atualização: 23 de jul. de 2026