ADRs
ADRs are deferred until a decision needs more than a focused reference page. Use this page as the candidate index: it names the choices likely to deserve full decision records later, while keeping the current durable explanation in the page that already owns the working context.
Promotion Rule
Section titled “Promotion Rule”Use roadmap sections and focused docs pages first. Promote a decision to a full ADR when it is:
- Durable enough that future contributors will ask why it happened.
- Cross-cutting across apps, packages, infrastructure, operations, or docs.
- Likely to be revisited, challenged, reversed, or applied to a future environment.
- More about tradeoff history than day-to-day procedure.
Do not create an ADR only to repeat a runbook, command reference, or page that already explains the current contract.
Candidate Index
Section titled “Candidate Index”| Candidate Decision | Current Reference Home | Why It May Need An ADR | Promote When |
|---|---|---|---|
| Use Astro/Starlight for the docs app | Docs Content Model and Docs Hosting | Docs framework choice affects content structure, hosting, search, generated artifacts, and future public docs maturity. | The docs site gains previews, versioning, generated API docs, or public audience requirements. |
| Host docs as an independent static surface | Deployment and Docs Hosting | Static docs hosting is intentionally separate from the app/API runtime, wake path, database, and rollback lane. | Docs deployment policy grows beyond the current single static site and publish workflow. |
| Use Pulumi TypeScript as the first infrastructure implementation | Infrastructure Change Policy | IaC language and state choices shape graph review, generated topology, output contracts, and provider posture. | A second environment, provider, or IaC boundary makes the original tradeoffs worth preserving. |
| Stay AWS-first while keeping provider-aware vocabulary | Infrastructure Change Policy | The project deliberately avoids pretending to be cloud-neutral while still preserving provider-aware concepts. | A second provider becomes concrete, or AWS-first assumptions start affecting package/API design. |
| Separate app/API deploy from infrastructure mutation | Deployment Workflows and Deployment | Routine CD intentionally deploys images and smoke checks without running pulumi up. | Infrastructure automation starts moving toward guarded workflow-driven updates. |
| Use a sleepable single-host deployed-dev runtime | Deployed Dev Environment and Deployed Dev Lifecycle | Cost, wake UX, containerized Postgres, and shared runtime lifecycle are tied together in the first cloud-backed target. | Staging, production, managed database, multi-host, or always-on topology work begins. |
| Treat deployed-dev data as disposable and backup as learning | Data Durability And Recovery | The current posture is an explicit non-production durability choice that future environments must not inherit blindly. | A backup/restore drill lands, or a later environment needs formal RPO/RTO and restore policy. |
| Keep the public CLI separate from typed operations helpers | Wavemap CLI and Wavemap CLI Command Reference | The package boundary keeps public route compatibility separate from typed planning, validation, and shell execution. | CLI distribution, generated command docs, or cross-environment command profiles become real. |
| Split media provider, execution target, and environment | Media Storage And Delivery and Media Workflow And Validation | The media model avoids persisting emulator identity while still supporting mocked, emulator, and cloud execution paths. | Cross-entity media, direct uploads, second-provider migration, or production media policy begins. |
| Keep raw topology private and publish sanitized projections | Generated Documentation and Infra Topology Processing | Generated infra evidence can expose sensitive-adjacent details; the public docs site receives only reviewed projections. | Automated topology publication, live inventory, graph diffs, or public generated diagrams mature. |
| Treat i18n as a platform package, not a frontend folder | i18n | Localization now spans frontend runtime, backend errors, email copy, generated assets, CI, and domain-code contracts. | A new app/runtime consumes i18n, or generated assets/CDN behavior becomes environment-specific. |
| Centralize shared API contracts across front end and back end | API Contracts | Shared route, DTO, envelope, permission, query, and domain-code contracts prevent app-local drift. | A new app, API version, generated client, or public API surface changes the contract boundary. |
Watchlist
Section titled “Watchlist”Some choices are important but should keep maturing in their focused pages before ADR promotion:
- Association-row modeling and high-cardinality relationship UX.
- Query controls, URL state, and saved views as reusable collection-page contracts.
- Server error localization and automated email copy through i18n adapters.
- Cloud automation permission review as a standing operations gate.
- Admin content model and future CMS authoring workflow.
These may become ADRs if they start shaping multiple packages, public workflows, or future environments.
Format Later
Section titled “Format Later”When the first full ADR is needed, prefer one page per decision with:
- Status.
- Context.
- Decision.
- Consequences.
- Alternatives considered.
- Current implementation references.
Keep full ADRs concise. They should preserve the reasoning that will be hard to recover later, not replace the reference pages that explain how the system works today.