mirror of
https://github.com/azaion/ui.git
synced 2026-04-22 22:36:35 +00:00
Oleksandr Bezdieniezhnykh
157 lines
4.8 KiB
Markdown
157 lines
4.8 KiB
Markdown
# 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.
|