DESIGN.md Documentation

When to Use This Skill

• Documenting system architecture
• Recording design decisions
• Creating technical specifications
• Onboarding new team members
• Reviewing system design

DESIGN.md Purpose

A DESIGN.md file provides high-level documentation of a software system's architecture, key design decisions, and technical approach. It serves as the authoritative source for understanding how a system works and why it was built that way.

Standard Template

# Design: [Project/Feature Name]

## Overview

Brief description of what this system/feature does and its primary purpose.

## Goals and Non-Goals

### Goals
- [Primary objective 1]
- [Primary objective 2]
- [Primary objective 3]

### Non-Goals
- [Explicitly out of scope item 1]
- [Explicitly out of scope item 2]

## Architecture

### System Diagram

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────▶│ API │────▶│ Database │ │ (React) │ │ (Node.js) │ │ (Postgres) │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Cache │ │ (Redis) │ └─────────────┘

### Components

#### [Component A]
- **Purpose**: What it does
- **Technology**: Stack used
- **Interfaces**: How it communicates

#### [Component B]
- **Purpose**: What it does
- **Technology**: Stack used
- **Interfaces**: How it communicates

## Data Model

### Entities

User ├── id: UUID ├── email: string ├── name: string ├── role: enum(admin, user) └── created_at: timestamp

Post ├── id: UUID ├── user_id: UUID (FK → User) ├── title: string ├── content: text └── published_at: timestamp

### Relationships
- User → Post: One-to-many

## API Design

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/users | List users |
| GET | /api/users/:id | Get user |
| POST | /api/users | Create user |
| PUT | /api/users/:id | Update user |
| DELETE | /api/users/:id | Delete user |

### Authentication
[Describe auth approach]

### Rate Limiting
[Describe rate limiting strategy]

## Key Design Decisions

### Decision 1: [Title]

**Context**: [What problem/situation prompted this decision]

**Options Considered**:
1. [Option A] - [Brief description]
2. [Option B] - [Brief description]
3. [Option C] - [Brief description]

**Decision**: [Which option was chosen]

**Rationale**: [Why this option was selected]

**Consequences**: [Trade-offs and implications]

### Decision 2: [Title]
[Same structure]

## Security Considerations

- [Security measure 1]
- [Security measure 2]
- [Security measure 3]

## Performance Considerations

- [Performance strategy 1]
- [Performance strategy 2]
- [Performance strategy 3]

## Testing Strategy

### Unit Tests
[Approach]

### Integration Tests
[Approach]

### E2E Tests
[Approach]

## Deployment

### Infrastructure
[Description of deployment infrastructure]

### CI/CD Pipeline
[Description of pipeline stages]

### Monitoring
[Description of monitoring approach]

## Future Considerations

- [Potential future enhancement 1]
- [Potential future enhancement 2]
- [Known technical debt]

## References

- [Link to related documentation]
- [Link to external resources]
- [Link to related designs]

ASCII Diagrams

System Flow

┌──────────────────────────────────────────────────────────────┐
│                        SYSTEM OVERVIEW                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│  │ Browser │───▶│   CDN   │───▶│  Load   │───▶│   App   │  │
│  │         │    │         │    │Balancer │    │ Server  │  │
│  └─────────┘    └─────────┘    └─────────┘    └────┬────┘  │
│                                                     │        │
│                                              ┌──────┴──────┐ │
│                                              ▼             ▼ │
│                                         ┌─────────┐  ┌──────┐│
│                                         │   DB    │  │Cache ││
│                                         │(Primary)│  │      ││
│                                         └────┬────┘  └──────┘│
│                                              │               │
│                                              ▼               │
│                                         ┌─────────┐          │
│                                         │   DB    │          │
│                                         │(Replica)│          │
│                                         └─────────┘          │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Sequence Diagram

Client          API           Database        Cache
   │              │               │              │
   │─── Request ──▶               │              │
   │              │── Check Cache ────────────▶ │
   │              │               │              │
   │              │◀─── Miss ─────────────────── │
   │              │               │              │
   │              │── Query ─────▶│              │
   │              │               │              │
   │              │◀─ Results ────│              │
   │              │               │              │
   │              │── Update Cache ─────────────▶│
   │              │               │              │
   │◀── Response ─│               │              │
   │              │               │              │

State Machine

                    ┌─────────┐
        ┌──────────│  DRAFT  │◀─────────┐
        │          └────┬────┘          │
        │               │ submit        │ reject
        │               ▼               │
        │          ┌─────────┐          │
        │          │ PENDING │──────────┤
        │          │ REVIEW  │          │
        │          └────┬────┘          │
        │               │ approve       │
        │               ▼               │
        │          ┌─────────┐          │
        └──────────│PUBLISHED│          │
         unpublish └─────────┘          │
                        │               │
                        │ archive       │
                        ▼               │
                   ┌─────────┐          │
                   │ARCHIVED │──────────┘
                   └─────────┘  restore

Decision Record Format (ADR)

# ADR-001: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[Describe the issue motivating this decision]

## Decision
[Describe the change we're making]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Drawback 1]
- [Drawback 2]

### Neutral
- [Trade-off 1]

Best Practices

Keep Updated

• Update when design changes
• Review during major refactors
• Mark outdated sections

Be Concise

• Focus on "why" not "what"
• Code shows implementation
• Design shows reasoning

Include Diagrams

• Visualize complex flows
• Use ASCII for portability
• Keep diagrams simple

Document Trade-offs

• Explain alternatives considered
• State explicit non-goals
• Acknowledge technical debt

Checklist

• Clear overview of purpose
• Goals and non-goals defined
• Architecture diagram included
• Key components documented
• Data model described
• API endpoints listed
• Design decisions recorded
• Security considerations noted
• Deployment process documented
• Future work identified