Design Docs

This section contains documents that are still in the design phase or worth referencing long-term. It focuses on comparing alternatives and implementation-ready details, but it is not the same as final decisions.

What belongs here

  • Requirement breakdown: goals, non-goals, constraints, boundaries
  • Alternatives: options, pros/cons, risks, migration paths
  • Interface / protocol design: HTTP/RPC/CLI, request/response, error codes, versioning strategy
  • Data structures & storage: schema, indexes, compatibility and evolution
  • Testing & observability: key cases, regression points, metrics and alerts

What does not belong here

  • Final conclusions that have been decided (put them in en/adr/ and link back from here)
  • Meeting notes and scattered discussions (put them in en/discussions/)
  • Background and problem statement
  • Goals / non-goals
  • Options and trade-offs
  • Compatibility and evolution
  • Delivery plan (milestones / rollback plan)