Repository Implementation Standard

Purpose

Repositories provide module-owned persistence access to PostgreSQL. They are private to their owning module.

Responsibilities

Responsibility	Standard
Ownership	Persist only module-owned source facts or projections.
Tenant filtering	Enforce TenantId and OrganizationId for customer data.
Persistence mapping	Map between persistence representation and domain/application models.
Optimistic locking	Support version checks for mutable records.
Soft delete	Apply soft-delete filtering where used.
Read models	Access owned read models through approved query repositories.

Rules

• Repositories are not injected into other modules.
• Repositories do not bypass application services.
• Repositories do not perform cross-module writes.
• Cross-module reads use APIs, events, projections, or approved read contracts.
• Repository implementations use parameterized access patterns and do not construct unsafe SQL from input.
• Repository tests must verify tenant filtering and ownership rules.

Persistence Flow

flowchart LR
    App[Application Service]
    Repo[Module Repository]
    Table[(Owned Tables)]
    ReadModel[(Owned Read Models)]

    App --> Repo
    Repo --> Table
    Repo --> ReadModel

Migration Alignment

Repository expectations must match Liquibase migrations and future database specifications owned by the same module.