# Component Specification Template

Use this template for each component. Save as `components/[##]_[name]/description.md`.

---

```markdown
# [Component Name]

## 1. High-Level Overview

**Purpose**: [One sentence: what this component does and its role in the system]

**Architectural Pattern**: [e.g., Repository, Event-driven, Pipeline, Facade, etc.]

**Upstream dependencies**: [Components that this component calls or consumes from]

**Downstream consumers**: [Components that call or consume from this component]

## 2. Internal Interfaces

For each interface this component exposes internally:

### Interface: [InterfaceName]

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `method_name` | `InputDTO` | `OutputDTO` | Yes/No | `ErrorType1`, `ErrorType2` |

**Input DTOs**:
```
[DTO name]:
  field_1: type (required/optional) — description
  field_2: type (required/optional) — description
```

**Output DTOs**:
```
[DTO name]:
  field_1: type — description
  field_2: type — description
```

## 3. External API Specification

> Include this section only if the component exposes an external HTTP/gRPC API.
> Skip if the component is internal-only.

| Endpoint | Method | Auth | Rate Limit | Description |
|----------|--------|------|------------|-------------|
| `/api/v1/...` | GET/POST/PUT/DELETE | Required/Public | X req/min | Brief description |

**Request/Response schemas**: define per endpoint using OpenAPI-style notation.

**Example request/response**:
```json
// Request
{ }

// Response
{ }
```

## 4. Data Access Patterns

### Queries

| Query | Frequency | Hot Path | Index Needed |
|-------|-----------|----------|--------------|
| [describe query] | High/Medium/Low | Yes/No | Yes/No |

### Caching Strategy

| Data | Cache Type | TTL | Invalidation |
|------|-----------|-----|-------------|
| [data item] | In-memory / Redis / None | [duration] | [trigger] |

### Storage Estimates

| Table/Collection | Est. Row Count (1yr) | Row Size | Total Size | Growth Rate |
|-----------------|---------------------|----------|------------|-------------|
| [table_name] | | | | /month |

### Data Management

**Seed data**: [Required seed data and how to load it]

**Rollback**: [Rollback procedure for this component's data changes]

## 5. Implementation Details

**Algorithmic Complexity**: [Big O for critical methods — only if non-trivial]

**State Management**: [Local state / Global state / Stateless — explain how state is handled]

**Key Dependencies**: [External libraries and their purpose]

| Library | Version | Purpose |
|---------|---------|---------|
| [name] | [version] | [why needed] |

**Error Handling Strategy**:
- [How errors are caught, propagated, and reported]
- [Retry policy if applicable]
- [Circuit breaker if applicable]

## 6. Extensions and Helpers

> List any shared utilities this component needs that should live in a `helpers/` folder.

| Helper | Purpose | Used By |
|--------|---------|---------|
| [helper_name] | [what it does] | [list of components] |

## 7. Caveats & Edge Cases

**Known limitations**:
- [Limitation 1]

**Potential race conditions**:
- [Race condition scenario, if any]

**Performance bottlenecks**:
- [Bottleneck description and mitigation approach]

## 8. Dependency Graph

**Must be implemented after**: [list of component numbers/names]

**Can be implemented in parallel with**: [list of component numbers/names]

**Blocks**: [list of components that depend on this one]

## 9. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Unrecoverable failures | `Failed to process order {id}: {error}` |
| WARN | Recoverable issues | `Retry attempt {n} for {operation}` |
| INFO | Key business events | `Order {id} created by user {uid}` |
| DEBUG | Development diagnostics | `Query returned {n} rows in {ms}ms` |

**Log format**: [structured JSON / plaintext — match system standard]

**Log storage**: [stdout / file / centralized logging service]
```

---

## Guidance Notes

- **Section 3 (External API)**: skip entirely for internal-only components. Include for any component that exposes HTTP endpoints, WebSocket connections, or gRPC services.
- **Section 4 (Storage Estimates)**: critical for components that manage persistent data. Skip for stateless components.
- **Section 5 (Algorithmic Complexity)**: only document if the algorithm is non-trivial (O(n^2) or worse, recursive, etc.). Simple CRUD operations don't need this.
- **Section 6 (Helpers)**: if the helper is used by only one component, keep it inside that component. Only extract to `helpers/` if shared by 2+ components.
- **Section 8 (Dependency Graph)**: this is essential for determining implementation order. Be precise about what "depends on" means — data dependency, API dependency, or shared infrastructure.