Develop Adr

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

Architecture Decision Record (ADR)

An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.

When to Use

• Making significant technical decisions that affect system architecture
• Choosing between technology options (frameworks, databases, services)
• Establishing patterns that future development should follow
• Documenting the rationale for constraints or non-obvious approaches
• Preserving institutional knowledge about past decisions

When NOT to Use

• The decision is a product or UX design choice, not architecture or technology -> use develop-design-rationale
• You are still exploring whether an approach is feasible -> time-box the exploration and record it with develop-spike-summary first
• You need to pitch a solution to stakeholders -> use develop-solution-brief; an ADR records a decision, it does not sell one
• Nothing is actually being decided (the status quo continues unchanged): an ADR without a decision is noise; wait until there is one

Instructions

When asked to create an ADR, follow these steps:

1. Assign a Number and Title ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."

2. Set the Status New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.

3. Describe the Context Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.

4. State the Decision Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.

5. Document the Consequences List the outcomes of this decision - positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?

Output Format

Use the template in references/TEMPLATE.md to structure the output. A complete ADR fills every template section: Status; Context; Decision; Consequences; Alternatives Considered; and References.

Quality Checklist

Before finalizing, verify:

• [ ] Title is a short, descriptive noun phrase
• [ ] Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
• [ ] Context explains why this decision was needed
• [ ] Decision is stated clearly in active voice
• [ ] Consequences include both positive and negative outcomes
• [ ] ADR can stand alone without requiring other documents

Examples

See references/EXAMPLE.md for a completed example.

Scenario: event-delivery backbone for order processing (high-tension ADR)

This is the INPUT brief for an output-quality eval. The skill arm and the control arm each receive everything below (and nothing else about how to do the work) and produce an Architecture Decision Record for it. Judges never see this header. This scenario is deliberately high-tension: three genuinely viable options with real, competing trade-offs, so a strong decision must weigh alternatives honestly and be candid about negative consequences, not just name a winner.

Situation

We run an e-commerce order-processing system on a Python/Postgres stack (one regional primary, read replicas). Today, order events (created, paid, fulfilled, refunded) are propagated by services polling a Postgres table every few seconds. This is now causing problems: downstream services (inventory, email, analytics, a new fraud-scoring service) get events seconds-to-minutes late, the polling load is hurting the primary, and a duplicate-charge incident last month traced back to two services both acting on the same order row with no clear ordering guarantee.

We need to choose an event-delivery backbone for the next 18 months. The decision is contested on the team; three options are on the table and each has a real champion.

Forces and constraints

• Team: 6 engineers, all strong in Python/Postgres, none with production Kafka experience. One

engineer ran Kafka at a previous job and is advocating for it.

• Delivery semantics: consumers need at-least-once delivery with a stable per-order ordering;

the fraud service in particular must not process "paid" before "created".

• Scale: ~400k orders/day now, expected ~3x in 18 months. Spiky (flash sales hit 10x for an hour).
• Multi-region: a second region (EU) is on the 12-month roadmap; data-residency rules will require

EU order data to stay in-region.

• Ops capacity: the team is already on-call for the monolith; appetite for a new always-on

distributed system to operate is low but not zero.

• Budget: a mid-four-figure monthly spend is acceptable; five-figure needs VP sign-off.
• Timeline: the fraud service launches in 10 weeks and needs ordered events by then.

Options on the table (each has a champion)

1. Self-hosted Apache Kafka - the advocate's pick; strong ordering + replay, but a new distributed system to operate with no in-house run experience, and multi-region adds real complexity. 2. A managed streaming service (e.g., a cloud provider's Kafka-compatible or pub/sub offering) - less ops burden, but cost at 3x scale is uncertain and EU data-residency must be verified per vendor. 3. Postgres transactional outbox + a lightweight relay - stay on the stack the team knows, exactly- once-ish via the outbox pattern and per-order ordering via the order id; but it is more code we own, has a throughput ceiling, and the relay is a new component to make reliable.

What the team wants

A decision record the team can align behind: a clear decision, the context and forces, the alternatives weighed with honest reasons each lost, and candid positive AND negative consequences (including what gets harder and what new risks appear), readable by someone who was not in the room.

Scenario: choosing the datastore for in-app search

This is the INPUT brief for an output-quality eval. The skill arm and the control arm each receive everything below (and nothing else about how to do the work) and produce an ADR for it. Judges never see this header.

Decision context

System: a B2B document-collaboration product (think shared docs + wikis) on a Postgres-backed monolith with a small platform team (4 engineers). We need to add full-text search across documents (title + body + comments), with filters by workspace, author, and date.

Why this is coming up now:

• Customers increasingly ask "I know I wrote it somewhere, I just can't find it." Search is the #2

requested feature.

• The current naive ILIKE query against Postgres is slow on large workspaces (some have 200k+ docs)

and cannot rank by relevance.

Forces and constraints the team named:

• The platform team is small and on-call already; operational burden matters a lot.
• Data must stay in our EU region (customer contracts); a managed service must offer EU hosting.
• Documents change constantly; near-real-time index freshness matters (stale results erode trust).
• Budget is constrained this year; a five-figure monthly search bill is a hard sell.
• The team has deep Postgres expertise and little Elasticsearch operational experience.

Options on the table (as the team framed them): 1. Postgres full-text search (tsvector/GIN) - no new infrastructure, but limited relevance tuning and weaker at typo tolerance and faceting. 2. Self-hosted Elasticsearch/OpenSearch - powerful and flexible, but a new cluster to operate, secure, and keep in sync; real ops cost for a 4-person team. 3. A managed search service (e.g., Elastic Cloud or a hosted search API) - less ops, more $$, and a data-residency/vendor question.

What is being decided: which datastore backs v1 of in-app search. The team wants the decision and its consequences recorded so future engineers understand why.

develop-adr - Version History

2.1.0 (2026-06-10)

Quality-convergence minor (F-12 Batch 2): added a "When NOT to Use" section with boundary pointers to neighboring skills, and the Output Format now enumerates the template sections a complete artifact fills. No template or example changes.

2.0.0 (2026-01-26)

Baseline row for the prior published version; see git history for its changes.

ADR-007: Use PostgreSQL for Order Data

Status

Accepted

Date: 2026-01-14 Deciders: Chen Wei (Tech Lead), Sarah Park (Architect), Marcus Johnson (DBA)

Context

We are building a new order processing service to replace our legacy monolith's order management module. This service will handle approximately 50,000 orders per day initially, with projected growth to 500,000 orders per day within two years.

The order data has the following characteristics:

• Strong consistency requirements (cannot lose or duplicate orders)
• Complex relationships (orders, line items, shipping addresses, payment records)
• Need for ACID transactions during order creation and updates
• Regulatory requirement to maintain complete audit history
• Reporting queries against order data by business analysts

Our team has experience with PostgreSQL, MongoDB, and DynamoDB. The company already runs PostgreSQL in production for other services, with established backup and monitoring infrastructure.

Timeline pressure exists: we need to launch the new service within 4 months to meet a deprecation deadline for the legacy system.

Decision

We will use PostgreSQL as the primary database for the order processing service.

Specifically:

• PostgreSQL 16 on AWS RDS with Multi-AZ deployment
• Read replicas for reporting workloads to avoid impacting transactional performance
• Use of native JSON columns for flexible order metadata while keeping core fields relational
• Connection pooling via PgBouncer

Consequences

Positive

• ACID compliance: PostgreSQL guarantees the transaction consistency we require for financial data. Order creation spanning multiple tables will either fully succeed or fully rollback.

• Team expertise: Three of our four backend engineers have significant PostgreSQL experience. No ramp-up time required, reducing project risk.

• Operational maturity: We leverage existing PostgreSQL infrastructure, monitoring (Datadog), and backup procedures. Our DBA team is already trained.

• Rich query capability: Complex reporting queries are straightforward with SQL joins. Business analysts can use existing BI tools without learning new query languages.

• Schema evolution: PostgreSQL's migration tooling (we use Flyway) provides controlled schema evolution with rollback capability.

Negative

• Horizontal scaling limits: PostgreSQL scales vertically well but horizontal sharding is complex. If we exceed 500K orders/day significantly, we may need to revisit this decision.

• Schema rigidity: Schema changes require migrations and potentially downtime for large tables. Adding new order attributes requires more planning than a document store.

• Cost at scale: RDS PostgreSQL is more expensive than DynamoDB for high-throughput simple lookups. At 500K orders/day, we estimate $3,200/month vs. $1,800/month for DynamoDB.

Neutral

• We will need to implement our own soft-delete and audit logging (PostgreSQL doesn't provide this natively like some enterprise databases).

• Read replica lag (typically <1 second) means reporting data may be slightly behind real-time.

Alternatives Considered

MongoDB

MongoDB's document model would provide more flexibility for evolving order schemas. However, our need for strong consistency in a distributed write scenario made MongoDB less attractive. The eventual consistency model, while configurable, adds complexity. Additionally, none of our current engineers have production MongoDB experience.

DynamoDB

DynamoDB would excel at high-throughput single-item lookups and offers seamless horizontal scaling. We rejected it because:

• Complex queries (e.g., "all orders for customer X in date range Y with status Z") require secondary indexes or full scans
• No native join capability means denormalizing data or making multiple queries
• The team would need to learn a new query paradigm and data modeling approach
• Cost advantage only materializes at scales we may not reach

CockroachDB

CockroachDB offers PostgreSQL compatibility with built-in horizontal scaling. We considered it for future-proofing but rejected it due to:

• Less operational experience in our organization
• Higher complexity for a team our size
• The PostgreSQL-compatible mode has some limitations that could surprise us

References

• Spike Summary: Database Options for Order Service (/spikes/order-db/summary.md)
• PostgreSQL 16 Release Notes (https://www.postgresql.org/docs/16/pm-release-16.html)
• ADR-003: Use AWS RDS for managed databases (establishes RDS as our database platform)
• Order Service Capacity Planning Document (/docs/order-service/capacity-planning.md)

ADR-[NNN]: [Decision Title]

Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

Date: [YYYY-MM-DD] Deciders: [List of people involved in the decision]

Context

<!-- What is the issue that we're seeing that is motivating this decision or change? What forces are at play (technical, business, organizational)? Include relevant constraints, team expertise, timeline pressures, etc. -->

[Describe the context and problem statement]

Decision

<!-- What is the change that we're proposing and/or doing? Use active voice: "We will..." not "It was decided..." Be specific about what is included and excluded. -->

[State the decision clearly]

Consequences

<!-- What becomes easier or more difficult to do because of this change? Include both positive and negative consequences. Be honest about trade-offs. -->

Positive

• [Positive consequence 1]
• [Positive consequence 2]
• [Positive consequence 3]

Negative

• [Negative consequence 1]
• [Negative consequence 2]

Neutral

• [Neutral observation or implication]

Alternatives Considered

<!-- Optional but recommended: document other options that were evaluated -->

[Alternative 1]

[Brief description and why it was not chosen]

[Alternative 2]

[Brief description and why it was not chosen]

References

<!-- Links to supporting documents, research, or related ADRs -->

• [Related ADR or document]
• [Research or spike summary]
• [External reference]