# Technical Specification

## 1. Overview

**Feature/Project**: {name}
**Author**: {name}
**Date**: {date}
**Status**: Draft / In Review / Approved

### Summary
{One paragraph describing what this technical spec covers and why.}

### Background
{Context needed to understand this spec. What exists today? What prompted this work?}

## 2. Architecture

### System Context
{How does this feature/system fit into the broader architecture? What systems does it interact with?}

### Component Design
{Describe the major components, their responsibilities, and how they interact.}

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Component A │────>│ Component B │────>│ Component C │
└──────┬──────┘     └─────────────┘     └─────────────┘
       │
       v
┌─────────────┐
│ Component D │
└─────────────┘
```

### Key Design Decisions
{Describe important design decisions and the reasoning behind them. For significant decisions, create a separate ADR.}

| Decision | Choice | Rationale | Alternatives Considered |
|----------|--------|-----------|------------------------|
| {what was decided} | {what was chosen} | {why} | {what else was considered} |

## 3. API Design

### Endpoint: {METHOD} {/path}

**Description**: {what this endpoint does}
**Authentication**: {required/optional/none}

**Request**:
```json
{
  "field": "type — description"
}
```

**Response (200)**:
```json
{
  "field": "type — description"
}
```

**Error Responses**:
| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_INPUT | {when this occurs} |
| 401 | UNAUTHORIZED | {when this occurs} |
| 404 | NOT_FOUND | {when this occurs} |

## 4. Data Model

### Table: {table_name}
{Description of what this table stores.}

| Column | Type | Nullable | Default | Description |
|--------|------|----------|---------|-------------|
| id | UUID | No | gen_random_uuid() | Primary key |
| {column} | {type} | {Yes/No} | {default} | {description} |
| created_at | TIMESTAMP | No | now() | Record creation time |
| updated_at | TIMESTAMP | No | now() | Last update time |

**Indexes**: {index definitions}
**Foreign Keys**: {FK relationships}

### Migration Plan
{How to migrate from the current schema to the new schema. Include data migration if needed.}

## 5. Security Considerations

- **Authentication**: {how users are authenticated for this feature}
- **Authorization**: {what permissions are required, how they are enforced}
- **Data sensitivity**: {what sensitive data is handled, how it is protected}
- **Input validation**: {what inputs are validated and how}
- **Audit logging**: {what actions are logged}

## 6. Testing Strategy

| Test Type | What It Covers | Tools |
|-----------|---------------|-------|
| Unit | {individual functions, edge cases} | {test runner} |
| Integration | {component interactions, API contracts} | {test runner} |
| E2E | {user flows, browser interactions} | {Playwright} |
| Performance | {load, latency, throughput} | {k6/artillery} |

### Key Test Scenarios
- {Scenario 1: description}
- {Scenario 2: description}
- {Scenario 3: description}

## 7. Deployment Plan

- **Deploy strategy**: {rolling/blue-green/canary}
- **Feature flags**: {any feature flags needed}
- **Rollback plan**: {how to rollback if something goes wrong}
- **Monitoring**: {what to monitor after deploy}
- **Runbook**: {link to runbook or inline steps for common issues}

## 8. Risks and Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {what could go wrong} | Low/Med/High | Low/Med/High | {how to prevent or handle it} |
| {what could go wrong} | Low/Med/High | Low/Med/High | {how to prevent or handle it} |