Repository Builder

The repository pattern abstracts data access logic from business logic using Protocol interfaces and mapper-driven transformations. Define a repository interface that works exclusively with business models, then implement it with concrete ORM adapters, keeping domain logic independent of persistence details.

Create a Protocol interface defining your data access contract, then build a SQLAlchemy implementation that maps between ORM and business models using dedicated mapper classes. This enforces type safety, testability, and separation of concerns across CRUD, bulk, and query operations.

Mappers translate ORM entities to business models in repository methods, keeping persistence implementation hidden. Store mappers in a dedicated mappers/ directory and invoke them during create, read, and update operations to maintain clean domain boundaries.

Yes. Protocol-based repository interfaces enable dependency injection and mock implementations for testing. Inject repositories into use cases and controllers, allowing you to swap real repositories with test doubles without coupling to ORM details.

Repositories manage transactions and enforce proper error handling with ValueError and NotFoundError exceptions. Implement logging and validation within repository methods to ensure data consistency and provide clear feedback when operations fail.

Protocol interfaces enable structural typing without inheritance, allowing flexible implementations and easier testing with mock objects. They define clear contracts for data access without enforcing a specific class hierarchy.