docs: define repository pattern boundary

docs/ARCHITECTURE.md

@@ -97,6 +97,28 @@ Domain code should not depend on delivery mechanisms, databases, network
 clients, or framework-specific runtime concerns unless the project intentionally
 uses an architecture where that trade-off is accepted and recorded.
 
+## Persistence Boundary
+
+The default persistence boundary is the repository pattern.
+
+Use repositories to express domain-specific persistence operations without
+leaking database, ORM, file-system, or external storage details into application
+or domain logic.
+
+Default rules:
+
+- Application or domain-facing code depends on repository interfaces.
+- Infrastructure implements repository interfaces.
+- Repositories are named around domain concepts, not database tables.
+- Repositories expose intention-revealing operations, not generic CRUD by
+  default.
+- Transaction boundaries are explicit at the application service, unit of work,
+  or framework boundary selected by the project.
+
+If a project intentionally avoids repositories because the framework or
+architecture provides a better persistence boundary, record that decision in
+[DECISIONS.md](DECISIONS.md).
+
 ## Request Flow
 
 ```mermaid

docs/CONVENTIONS.md

@@ -125,9 +125,15 @@ Project-specific DTO rules:
 
 ## Repository Rules
 
-Repositories, gateways, or data access abstractions should express persistence
-intent without hiding important consistency behavior.
+Use the repository pattern as the default persistence boundary.
 
+Repositories, gateways, or data access abstractions should express domain
+persistence intent without hiding important consistency behavior.
+
+- Define repository interfaces at the application or domain boundary.
+- Implement repositories in infrastructure or persistence-specific modules.
+- Prefer specific repositories such as `OrderRepository` or
+  `SupportRequestRepository`.
 - Keep query methods specific enough to reveal purpose.
 - Avoid generic repositories when they obscure domain behavior.
 - Document transaction boundaries.

docs/DECISIONS.md

@@ -25,6 +25,7 @@ For project constraints, see [PROJECT.md](PROJECT.md).
 | ADR-001 | Example: Start with a modular monolith | Example | 2026-06-28 |
 | ADR-002 | Example: Keep project documentation in the repository | Example | 2026-06-28 |
 | ADR-003 | Example: Require explicit validation evidence before merge | Example | 2026-06-28 |
+| ADR-004 | Example: Use repository pattern for persistence boundaries | Example | 2026-06-28 |
 
 ## ADR-000: ADR Template
 
@@ -245,3 +246,62 @@ manual checks, or reasons validation could not be run.
 - PR templates should include validation.
 - Reviewers can block merges when risk is high and evidence is missing.
 - Failed or skipped validation must be explained.
+
+## ADR-004: Example: Use Repository Pattern For Persistence Boundaries
+
+### Title
+
+Use repository pattern for persistence boundaries.
+
+### Status
+
+Example
+
+### Date
+
+2026-06-28
+
+### Context
+
+The project needs domain and application logic to remain independent from the
+database engine, ORM, and storage implementation details.
+
+### Problem
+
+Without an explicit persistence boundary, database concerns can leak into
+business logic and make testing, refactoring, and future storage changes harder.
+
+### Alternatives
+
+| Alternative | Summary |
+| --- | --- |
+| Direct ORM access everywhere | Fast initially, but couples business logic to persistence details. |
+| Generic repository | Reduces ORM exposure, but often becomes a thin CRUD wrapper. |
+| Domain-specific repository pattern | Keeps persistence behind intention-revealing interfaces. |
+
+### Pros
+
+- Keeps application and domain logic focused on use cases and rules.
+- Makes persistence behavior easier to test and replace.
+- Creates a clear place for query intent and transaction expectations.
+- Reduces accidental coupling to ORM-specific APIs.
+
+### Cons
+
+- Adds interfaces and implementation classes.
+- Poorly designed repositories can hide important query or transaction costs.
+- Generic repositories can obscure domain behavior if used mechanically.
+
+### Decision
+
+Use domain-specific repositories as the default persistence boundary.
+
+### Consequences
+
+- Repository interfaces should live at the application or domain boundary.
+- Repository implementations should live in infrastructure or persistence
+  modules.
+- Generic CRUD repositories should be avoided unless the project records a clear
+  reason.
+- Transaction boundaries must be documented where writes span multiple
+  repositories.