What are architecture decision records?
An architecture decision record (ADR) is a short document that captures a single non-trivial technical decision made during a project’s development. Each ADR records:- The context — the forces, constraints, and trade-offs that influenced the decision
- The decision — what was decided, stated clearly and in active voice
- The consequences — the resulting effects, both positive and negative
Why this project uses ADRs
Web-unified-docs is a complex system that combines content processing, API design, build tooling, and migration workflows. Without a decision log, it becomes difficult to understand why the system was built the way it was — which makes maintenance, iteration, and onboarding harder. The project adopted ADRs (ADR 000) for the following reasons:- Decisions made during implementation are documented alongside the code
- Future maintainers can understand the reasoning behind architectural choices without needing to excavate old PRs or Slack threads
- Decisions are made more intentionally when there is a lightweight process to articulate and record them
How to read an ADR
Each ADR follows the template described in Michael Nygard’s Documenting Architecture Decisions. The sections are:| Section | What it contains |
|---|---|
| Status | proposed, accepted, deprecated, or superseded (with a reference to the replacement ADR) |
| Context | A value-neutral description of the forces and constraints that made a decision necessary |
| Decision | What was decided. Written in active voice: “We will…” |
| Consequences | All effects of the decision — positive, negative, and neutral |
docs/decisions/ and named adr-NNN-title-in-dash-case.md.
ADRs in this project
ADR 000: Document architecture decisions
Establishes the practice of using ADRs in this project. Defines the format, template, and storage location for all future ADRs.
ADR 001: Parity with existing API
The unified docs API will implement the same GET endpoints as the existing
content.hashicorp.com API. This reduces migration complexity and avoids requiring front-end changes during the transition.ADR 002: Apply MDX transforms at build time
Certain MDX transforms — especially the
@include partial transform — must be applied before content is served. This ADR decides to apply those transforms during the prebuild script rather than at request time.ADR 003: Author content outside the public directory
MDX source files are stored in
content/ rather than public/. Transformed output is written to public/content/ and excluded from version control. This separates authored source from build output.ADR 004: Parity with existing API (Jan 2025 update)
An update to ADR 001, extending the API parity commitment to include the
/api/static_paths endpoint, following decisions made during 2024 Q3 and 2025 Q1 milestone planning.How to propose a new ADR
Identify a non-trivial architectural decision
An ADR is appropriate when you face a decision that involves real trade-offs — where multiple approaches are plausible and the choice has lasting consequences. Trivial implementation details do not need ADRs.
Create the ADR file
Create a new file in Use the next available number for
docs/decisions/ following the naming convention:NNN.