CAP outbox publish sequence

Question and use cases

Commit first, dispatch afterward, then acknowledge or retry at the consumer boundary.

Use this sequence to place event publication relative to handler work, database commit, and consumer acknowledgement.

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: Trace the command through the transaction behavior into the handler.
2. Step 2: Keep the state write and outbox append inside the same database transaction.
3. Step 3: Treat broker delivery and consumer acknowledgement as later, retryable phases.

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 SEQUENCE 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: The handler changes state inside the transaction behavior.

Architectural meaning: The transaction behavior provides one boundary for aggregate change and the outbox append initiated by the handler.

Review action: Could a crash commit state without recording the event?

Relationship 2

Source fact: CAP appends the integration event to the outbox before the database transaction commits.

Architectural meaning: The outbox row is durable before CAP attempts broker delivery, so delivery can resume after process failure.

Review action: Can the consumer safely process the same event more than once?

Relationship 3

Source fact: A consumer acknowledgement or retry happens after broker delivery.

Architectural meaning: Acknowledgement belongs after consumer work; retries otherwise risk acknowledging data that was never applied locally.

Review action: Is acknowledgement sent only after local consumer work succeeds?

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.

• Could a crash commit state without recording the event?
• Can the consumer safely process the same event more than once?
• Is acknowledgement sent only after local consumer work succeeds?

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

Do not publish to the broker directly before the state commit.

• 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: Can the consumer safely process the same event more than once?

Boundary 2

A retry can deliver the same event again, so the consumer must remain idempotent.

• 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 acknowledgement sent only after local consumer work succeeds?

Source verification and regeneration

The primary verification entry point is BitzOrcas.Infrastructure.SqlSugar.Outbox.Cap/CapSqlSugarUnitOfWork.cs + BitzOrcas.Infrastructure.EfCore.Outbox.Cap/CapEfCoreUnitOfWork.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.

Continue reading

• Architecture overview
• All architecture diagrams
• Platform modules