Question and use cases

SqlSugar or EF Core owns writes; Dapper complements query-oriented reads.

Use this map when selecting a persistence provider or deciding whether a query belongs on the write or read side.

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

Step 1: Begin with application repository and query ports.
Step 2: Follow the configured write provider to SqlSugar or EF Core.
Step 3: Read Dapper as an explicit read adapter that can coexist with either write provider.

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

Visual element	Meaning	What it does not imply
Coral focus	The decision point or primary path emphasized by this view	That the element is always more important or privileged
Blue boundary	An external system, protocol edge, or explicit boundary	That it must be an independently deployed service
Muted connector	A dependency, call, transition, or data flow as named by its label	Synchronous, same-transaction, or exactly-once behavior
Group frame	A responsibility, layer, or lifecycle phase	A team or physical-machine boundary

This is a ADAPTER MAP 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: Persistence:Provider selects SqlSugar or EF Core for generated write-side adapters.

Architectural meaning: Provider choice remains a deployment/composition decision instead of branching application handlers by ORM.

Review action: Does application code remain free of provider-specific APIs?

Relationship 2

Source fact: Dapper is registered for explicit query/read-model access alongside the selected write provider.

Architectural meaning: Explicit Dapper access supports optimized projections without pretending that it supplies write tracking or aggregate persistence.

Review action: Are tenant, transaction, concurrency, and diagnostics semantics preserved?

Relationship 3

Source fact: Application code depends on repository and query ports rather than ORM-specific APIs.

Architectural meaning: Stable ports give architecture tests and consumer tests a common seam for provider parity.

Review action: Is a read-model optimization isolated behind a query port?

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.

Does application code remain free of provider-specific APIs?
Are tenant, transaction, concurrency, and diagnostics semantics preserved?
Is a read-model optimization isolated behind a query port?

How to use the answers

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

Boundaries and common mistakes

Boundary 1

SqlSugar, EF Core, and Dapper are not three interchangeable full-stack providers.

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: Are tenant, transaction, concurrency, and diagnostics semantics preserved?

Boundary 2

Tenant filtering and transaction semantics must remain consistent across adapters.

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 a read-model optimization isolated behind a query port?

Source verification and regeneration

The primary verification entry point is src/Hosts/BitzOrcas.Api/Composition/PersistenceRegistration.cs. 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.

Persistence adapter composition