# Common Patterns

## Reuse Before Building

When implementing substantial new functionality:

1. Search the repository for existing patterns and utilities.
2. Check mature libraries, templates, or reference implementations when they can reduce risk.
3. Evaluate security, maintenance, relevance, and extensibility.
4. Adopt the simplest proven foundation that satisfies the requirement.

When independent evaluations are useful, run available tools in parallel only if the current Pi harness supports parallel calls. Delegate to child Pi sessions only through an installed Pi extension or external workflow, and always collect and verify every result.

## Repository Pattern

Encapsulate data access behind a consistent interface:

- Define standard operations such as `findAll`, `findById`, `create`, `update`, and `delete`.
- Let concrete implementations handle storage details.
- Keep business logic dependent on the interface rather than a specific database or API.
- Use test doubles at the interface boundary.

Apply this pattern only when multiple data sources, testing needs, or domain complexity justify the abstraction.

## API Response Format

Use a consistent response envelope when the existing API follows one:

- include a success or status indicator;
- include the data payload on success;
- include a safe error message on failure;
- include pagination metadata when relevant.

Prefer the project's established contract over introducing a competing format.