Docs Components Design

Docs Components Design

Maintain technical design docs for implementation units. Put contracts, state, runtime behavior, and operational detail here rather than in feature or architecture docs.

Resource Map

• Use assets/doc-starters/component-design-doc.md when creating or substantially rewriting a doc in docs/designs/.
• Read references/component-design-example.md when you need a worked example of the expected technical depth.

When to Use

• New service, worker, module, integration surface, or shared component
• Changes to interfaces, contracts, schema, queues, state machines, or external integrations
• Changes to concurrency, retries, failure handling, security boundaries, or operational behavior
• Technical design updates that should not live in feature docs

Do Not Use

• System or domain topology docs that belong in docs-architecture
• User-facing feature behavior and goals that belong in docs-feature-design

Workflow

1. Identify the implementation unit and current doc path.

• Default location is docs/designs/
• Reuse an existing design doc when one already exists

2. Capture the technical shape of the change.

• Problem and scope
• Interfaces and contracts
• Data model or state changes
• Runtime behavior, failure modes, and operations
• Security and ownership boundaries

3. Keep feature and architecture boundaries clean.

• Link to relevant feature docs instead of retelling the product story
• Link to architecture docs instead of restating system topology

4. Verify against the repo.

• Commands, migrations, contracts, and runtime behavior match the current code
• Design decisions still reflect the active implementation

5. Trim low-value detail.

• Avoid path dumps and copied code
• Keep only the technical detail needed to understand and maintain the component

Writing Rules

• Technical detail belongs here
• Prefer concise summaries of contracts, schemas, and state over long pasted definitions
• If one component supports multiple features, describe the reusable implementation capability rather than a single feature narrative
• Make trade-offs, failure modes, and ownership explicit
• The Technical Design sub-sections (Interfaces, Data Model, Runtime, Security) are a baseline — add domain-specific sections (Processing Flow, Algorithm, Examples, Configuration) at the same level when they clarify the design better than generic sub-sections would

Quality Checklist

• The doc clearly names the component or service scope
• Contracts, state, and runtime behavior are accurate
• Operational and security details are current
• Feature behavior is linked out rather than embedded
• Architecture context is referenced rather than duplicated