gh-onezerocompany-claude-project-basics/skills/spec-author/templates/design-document.md

Design Document

Type: Status: Version:

Executive Summary

Problem Statement

Goals & Success Criteria

Primary Goals

• Goal 1:
• Goal 2:
• Goal 3:

Success Criteria

Context & Background

Proposed Solution

High-Level Overview

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ├─→ [API Gateway]
       │         │
       ├─→ [Service Layer]
       │    ├─ Service A
       │    └─ Service B
       │
       └─→ [Data Layer]
            ├─ Database
            └─ Cache

Architecture Components

• Purpose:
• Technology:
• Key Responsibilities:
• Interactions:

• Purpose:
• Technology:
• Key Responsibilities:
• Interactions:

Design Decisions

Decision 1:

• Decision:
• Rationale:
• Alternatives Considered:
• Impact:

Decision 2:

• Decision:
• Rationale:
• Alternatives Considered:
• Impact:

Technology Stack

Language & Runtime

Data Layer

Infrastructure

Key Libraries/Frameworks

Data Model & Storage

Storage Strategy

• Primary Database:
• Caching:
• Data Retention:

API & Integration Points

External Dependencies

• Integrates with for
• Consumes events from
• Publishes events to

Key Endpoints (or reference API spec)

• :
• :

Trade-offs

Accepting

Gaining

Implementation

Approach:

Phases:

1. Phase 1:
2. Phase 2:
3. Phase 3:

Migration Strategy (if applicable):

See Plan Specification for detailed implementation roadmap.

Performance & Scalability

Performance Targets

• Latency:
• Throughput:
• Availability:

Scalability Strategy

• Scaling Approach:
• Bottlenecks:
• Auto-scaling:

Monitoring & Observability

• Metrics:
• Alerting:
• Logging:

Security

Authentication

Authorization

Data Protection

• Encryption at Rest:
• Encryption in Transit:
• PII Handling:

Secrets Management

Compliance

Dependencies & Assumptions

Dependencies

Assumptions

Open Questions

• - Status:
• - Status:

Approvals

Technical Review

Architecture Review

Security Review

Approved By