admin/.cursor/skills/plan/templates/component-spec.md

Component Specification Template

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

---

# [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.