Design Doc Standards

Design Doc Standards

To maintain a high-quality “Time Capsule” of architectural decisions, all design documents in this repository must adhere to the following standards.

1. Naming Convention

Files must be named using the format: YYYY-NNN-kebab-case-title.md

• YYYY: The 4-digit year (e.g., 2026).
• NNN: A sequential 3-digit number starting at 001 for that year.
• Title: A concise, kebab-case description.

Example: 2026-001-auth-migration.md

2. Frontmatter

Every document must include the following Starlight frontmatter:

---
title: "YYYY-NNN: Title of Doc"
sidebar:
  order: 1 # Increment this based on the sequence
---

3. Required Structure

Every document must follow this high-level structure. Sub-sections are encouraged to organize complex technical details.

Metadata Table

The document must start with a summary table:

Metadata	Details
Status	Draft / Approved / Implemented / Deprecated
Author	Your Name
Scope	Components affected (e.g., Database, UI, API)
Created	YYYY-MM-DD

Section 1: Executive Summary

A concise paragraph summarizing the problem and the proposed solution.

Section 2: Context & Problem Statement

Explain the current state and the specific pain points or requirements driving the change.

Section 3: Proposed Architecture

The core of the document. This should include:

• System Design: Data models, partitioning, and flows.
• Security & IAM: How access is controlled.
• Technology Choices: Justifications for specific libraries or patterns (e.g., “Why CASL?”).
• Package/System Structure: How the code is organized across the monorepo.

Section 4: Implementation & Migration Plan

The roadmap for landing the change.

• Workflows: New user interactions or system processes.
• Deprecations: What old code/data is being replaced.
• Phases: Step-by-step rollout (Preparation, Migration, Deployment, Cleanup).

Section 5: Alternatives Considered

Briefly explain other paths that were explored and why they were not chosen.

4. Lifecycle

1. Draft: Create PR. Discuss in comments. Update doc based on feedback.
2. Approved: Merge PR. Status changes to Approved.
3. Implemented: When code lands, update status to Implemented (optional but recommended).
4. Deprecated: If a new design supercedes this one, mark as Deprecated and link to the new doc.