component.md•2.72 kB
# Component: [Component Name]
**Location:** `[path/to/component]`
**Last Updated:** [YYYY-MM-DD]
**Owner/Expert:** [Name if applicable]
## Purpose
[Clear description of what this component does and why it exists]
## Architecture
[How this component is structured internally]
```
component/
├── file1.ts # [Purpose]
├── file2.ts # [Purpose]
└── index.ts # [Purpose]
```
## Key Files
### `[filename]`
**Lines:** [Total or key ranges]
**Purpose:** [What this file does]
**Key Functions/Classes:**
- `functionName()` - [What it does]
- `ClassName` - [What it represents]
### `[another-file]`
**Lines:** [Total or key ranges]
**Purpose:** [What this file does]
## Dependencies
**Depends On:**
- `[component/module]` - [Why/how it's used]
- `[package]` - [Version, purpose]
**Used By:**
- `[component]` - [How it uses this]
- `[another-component]` - [How it uses this]
## Common Patterns
### [Pattern Name]
```typescript
// Example of how this component is typically used
[code example]
```
**When to use:** [Scenario]
**Parameters:** [Explanation]
**Returns:** [What it provides]
### [Another Pattern]
```typescript
[code example]
```
## Configuration
[Environment variables, config files, or settings this component uses]
```
ENV_VAR=value # [Purpose]
CONFIG_KEY=value # [Purpose]
```
## State Management
[How this component manages state, if applicable]
- **State Location:** [Where state lives]
- **Update Pattern:** [How state changes]
- **Persistence:** [If/how state is saved]
## Error Handling
[How errors are handled in this component]
- `ErrorType1` - [When thrown, how to handle]
- `ErrorType2` - [When thrown, how to handle]
## Testing
**Test Location:** `[path/to/tests]`
**Coverage:** [Percentage or description]
**Key Test Cases:**
- [Test scenario 1]
- [Test scenario 2]
**How to test:**
```bash
[command to run tests]
```
## Common Tasks
### [Task Name]
**Goal:** [What you're trying to do]
**Steps:**
1. [Step with file references]
2. [Another step]
3. [Verification]
### [Another Task]
**Goal:** [What you're trying to do]
**Steps:**
1. [Step]
## Gotchas
[Known issues, quirks, or non-obvious behaviors]
1. **[Gotcha Title]** - [Description and how to avoid]
2. **[Another Gotcha]** - [Description]
## Performance Considerations
[Any performance-related notes]
- [Consideration 1]
- [Consideration 2]
## Related
- **Sessions:** [Links to sessions that worked on this component]
- **ADRs:** [Links to relevant architectural decisions]
- **Components:** [Links to related components]
## Future Work
- [ ] [Potential improvement]
- [ ] [Technical debt]
- [ ] [Feature idea]
## Notes
[Any additional context that doesn't fit elsewhere]