Persistence adapter responsibilities

Question and use cases

The three adapters share application contracts but do not have identical runtime roles.

Use this comparison when implementing provider parity or evaluating a provider-specific optimization.

Use the diagram during design review, incident diagnosis, code walkthroughs, and onboarding. It intentionally omits classes and projects unrelated to the focused question, so read it together with the source entry point and related topic pages.

This page covers only the named responsibilities and relationships; consult the relevant module documentation for capabilities not shown here.

Reading path

1. Step 1: Compare SqlSugar and EF Core as alternative write-side adapters.
2. Step 2: Read Dapper separately as explicit query and read-model access.
3. Step 3: Return to the shared port boundary to judge parity.

Do not skip arrow direction, numbering, or group titles: they express dependency or time direction, execution order, and responsibility boundaries. If the diagram differs from current source or accepted architecture decisions, correct the generated catalog immediately.

Legend and notation

This is a COMPARISON diagram. Use that form to understand the layout, then test your interpretation against the source facts below.

Key relationships and design meaning

Relationship 1

Source fact: SqlSugar and EF Core are alternative write-side providers selected at composition time.

Architectural meaning: Only one write provider is selected for a composed runtime, avoiding competing units of work for the same aggregate path.

Review action: Do all providers preserve the same application-visible behavior?

Relationship 2

Source fact: Dapper implements explicit query and read-model access rather than change tracking.

Architectural meaning: Dapper optimizes explicit reads without inheriting responsibilities such as change tracking or aggregate lifecycle management.

Review action: Is tenant filtering impossible to forget on an adapter path?

Relationship 3

Source fact: All adapters must honor shared repository/query contracts, tenant filters, and diagnostics.

Architectural meaning: Parity at the shared contract boundary lets provider-specific internals differ while preserving tenant safety and observable outcomes.

Review action: Does an optimization remain hidden behind the provider adapter?

Design review questions

Answer each question when reviewing or implementing a related change. If code, tests, or an ADR cannot support the answer, do not decide from the diagram alone.

• Do all providers preserve the same application-visible behavior?
• Is tenant filtering impossible to forget on an adapter path?
• Does an optimization remain hidden behind the provider adapter?

How to use the answers

1. Identify the single owner of the capability or rule.
2. Confirm that dependency, call, or event direction does not reverse ownership.
3. Capture the conclusion with an automated test or repeatable command.

Boundaries and common mistakes

Boundary 1

Feature parity is required at the contract boundary, not at every ORM API surface.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Is tenant filtering impossible to forget on an adapter path?

Boundary 2

A provider-specific optimization stays behind its adapter and must not leak into application handlers.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Does an optimization remain hidden behind the provider adapter?

Source verification and regeneration

The primary verification entry point is BitzOrcas.Api/PersistenceRegistration.cs + adapter projects. Inspect it and its direct references before regenerating diagram assets and pages.

# Regenerate bilingual SVG, standalone HTML, and documentation pages
npm run diagrams

# Check locale pairs, references, safety attributes, accessibility, and canvas bounds
npm run verify:diagrams

# Confirm that generation changed only the intended diagrams and pages
git diff -- scripts/diagrams diagram-sources public/diagrams src/content/docs

# Verify internal links, MDX structure, and professional depth gates
npm run verify:docs
npm run audit:docs-depth

Change-completion checklist

• Responsibilities, order, states, and relationships match current source.
• Every new element helps answer this page’s question instead of turning the diagram into an inventory.
• Arrows have explicit direction and semantics without implying nonexistent synchronous or transactional guarantees.
• Chinese and English titles, labels, facts, and boundaries remain semantically equivalent.
• The diagram remains readable on narrow screens, in fullscreen, and while zoomed, with no overlap or overflow.
• Relevant architecture tests, integration tests, or verification commands have run.
• If a long-lived constraint changed, its ADR or architecture documentation is updated.

Continue reading

• Architecture overview
• All architecture diagrams
• Platform modules