Design doc: [Feature name]

Author

Reviewers

Status

Last updated

Links

Summary

The problem, the proposal and the main trade-off, in three to five sentences.

Decision needed, and by when:

See an example summary

Summary: Checkout calls the tax vendor on every order, and when the vendor is slow, checkouts time out: 4% failed this way in Q3, about 2,100 orders a week. We propose caching tax rates by region for 24 hours and calling the vendor only on a cache miss, which takes the vendor out of the checkout path for about 95% of orders. The trade-off is that a rate change can take up to a day to reach checkout. Finance has accepted that for every region except Quebec, which keeps the live call.

Decision needed, and by when: Approval of the 24-hour cache by March 14, so it ships before the April price change.

Context and scope

What exists today, what's wrong with it, and how you know.

Goals and non-goals

Goal

Measured by

Non-goals

Proposed design

Overview

The approach, then a context diagram.

How it works

APIs and data

Interface or store

Change

Details

Example request, event or record:

{
  "id": "<id>",
  "<field>": "<value>",
  "created_at": "<ISO 8601 timestamp>"
}

Migration and compatibility:

Alternatives considered

Describe each as its strongest advocate would.

Alternative

What it has going for it

Why we didn't choose it

Do nothing

Cross-cutting concerns

  • Security:

  • Privacy:

  • Reliability:

  • Observability:

  • Testing:

  • Cost:

Risks

Risk

Impact

Mitigation

Owner

Open questions

Tick each one when it's answered.

Rollout plan

Phase

What changes

Who is affected

Date

1

2

3

Rollback

See an example rollout

Phase

What changes

Who is affected

Date

1

Cache on behind a flag, off by default

Internal staff

Mar 18

2

Flag on for 5% of traffic; compare errors and tax totals

5% of customers

Mar 25

3

Flag on for everyone; delete the old call path

All customers

Apr 1

Rollback

Turn the flag off; takes effect in under a minute

Any on-call engineer

Any time

Decision

Outcome:

Approved by, and when:

Changes agreed in review: