Architecture doc template
The architecture doc says how the system will meet the PRD and the UX spec: what the parts are, what data they own, how they talk, and why you chose this design over the alternatives.
Templates · Architecture doc template
Template 4 of 10
architecture.md
# Architecture · <system> ## Context What talks to what. A diagram helps. ## Components Responsibility, which data it owns, how it scales. ## Data model Entities, key fields, relationships, retention. ## APIs Endpoints or events, request and response shape, errors, auth. ## Non-functional How each NFR from the PRD is met, with numbers. ## Security & privacy Auth, permissions, PII, audit. ## Decisions ADR style: decision, options considered, why. ## Risks Each with likelihood, impact, mitigation. ## Open questions
When to write it
Once the PRD and UX spec are approved, before stories are estimated. The architecture is where hidden work shows up: a migration, a new queue, a dependency on another team.
How to fill it in
- Context. One diagram of the systems involved and who calls whom. If a reviewer can't see where the new part sits in 30 seconds, start here.
- Components and data. For each part: what it's responsible for and which data it owns. Two components writing the same table is a decision to write down, not an accident to discover.
- Non-functional. Go through every NFR in the PRD and say how it's met, or flag it as unmet. "NFR-1: 95% of 1,000-row files in under 10 seconds: matching runs in one query against an index on SKU; measured 2.1 s for 1,000 rows on staging."
- Decisions. Short ADRs: the decision, the options you considered and why you rejected them. Future you will want to know why it isn't the obvious design.
- Risks. Likelihood, impact and what you'll do about each. Prefer boring, proven choices, and say which exciting ones you passed on.
Common mistakes
- A tour of the whole system instead of what changes.
- NFRs silently dropped.
- Decisions without the alternatives, so they get relitigated in code review.
Example
Architecture · Bulk orders
Components
- Upload API receives the file, stores it in object storage, starts a match job.
- Matcher reads the file, matches rows by SKU, writes results to
upload_rows. - Cart reads matched rows when the buyer adds them; it owns cart lines as today.
Non-functional
- NFR-1: rows are matched in one batched query on an index over
products.sku; 1,000 rows took 2.1 s on staging. - NFR-2: a nightly job deletes files 24 hours after their order is placed.
Decisions
Match on the server, not in the browser. Options: parse in the browser and send rows; parse on the server. Chose the server: one implementation for .xlsx and .csv, and suggestions need the full catalogue.
Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Customers use their own SKUs | Medium | High | A per-account SKU map, behind FR-2's suggestions |
Have Releavo write the architecture doc
In Releavo this lives at docs/architecture.md. Releavo drafts it from the docs before it and your team's conversations; every edit is a draft until the tech lead approves it, and approved versions are never overwritten.