Skip to content

Request for Comments

Proposals for non-trivial features or changes, debated before implementation begins. Once an RFC is Accepted, the resulting design decisions get captured as one or more ADRs, the implementation plan turns into a Plan, and the feature gets built.

When to write one

Write an RFC for any change that:

  • Touches more than one module
  • Adds a new data model or wire protocol
  • Has multiple plausible designs
  • Locks in a third-party dependency
  • Would be hard to roll back if it doesn't work out

Skip RFCs for one-file fixes, refactors that don't change behaviour, and additions to existing patterns.

Process

  1. Draft. Copy the template, fill it out, name it NNNN-slug.md, set status Draft.
  2. Review. Status In review. MASTER reads it, comments inline, suggests changes.
  3. Decide. Status Accepted (build it) or Rejected (with brief reason).
  4. Implement. Convert the implementation plan to GitHub issues. As decisions lock in during build, write ADRs.
  5. Close. Status Implemented once the work ships. Link to the merged PRs.

Conventions

  • Numbered sequentially across all RFCs (not per status).
  • Use the template.
  • Keep proposals scoped. One RFC, one feature.

Index

RFC Title Status Related
RFC-0001 Hosting target for the web app and workers Accepted #19
RFC-0002 Background-jobs runtime Accepted #18
RFC-0003 Search backend for product browse and build picker Accepted #39
RFC-0004 Frontend stack and component library (shadcn/ui) Accepted #27, #28, #42
RFC-0005 Compliance baseline (cookie banner, affiliate disclosure, ToS/privacy origin, retention windows, liability disclaimer) Accepted #40, ADR-0014
RFC-0006 Security controls (Auth.js scope, CSP, rate-limit topology, audit-log retention, vulnerability disclosure) Accepted #44, #11, #16, #17, #40, ADR-0012
RFC-0007 Observability stack (logs, errors, metrics, RUM, alerting) Accepted #43, ADR-0015
RFC-0008 Monetisation + pricing model (CPS 1.5% primary, CPC fallback, featured optional) Accepted #41, #17, #16, #28, #40, ADR-0011
RFC-0009 AI discoverability (LLM-citable surface) Accepted #47, ADR-0013