Docs/per service flow diagrams

[emeraldleaf]

What changed

How it was built

Verification

Touches (check only if applies)

• EF Core migration (immutable once applied — see CLAUDE.md "Performance Rules")
• CLAUDE.md or a See CLAUDE.md paraphrase (run /check-rules to audit drift)

Summary by CodeRabbit

• Documentation
  • Expanded infrastructure status note with clearer mitigation tiers and cross-references.
  • Added a contributor-facing code-flow index and detailed per-service walkthroughs covering request/event choreography, state machines, read/write patterns, idempotency/concurrency guidance, diagrams, and file inventories.

[coderabbitai]

Walkthrough

This PR adds contributor-facing per-service code-flow walkthroughs for Order, Payment, Shipping, Catalog, and Notification services and updates STATUS.md cache-backplane guidance.

Changes

Microservice Code-Flow Documentation Suite

Layer / File(s)	Summary
Status update and code-flow documentation index docs/STATUS.md, docs/code-flows.md	Cache backplane mitigation context is expanded with three remediation tiers. Index document introduces five service walkthroughs with saga-role mapping, end-to-end choreography diagram, and shared diagram authoring conventions.
OrderService request-to-saga walkthrough docs/code-flows/orderservice.md	Request-driven order placement validates stock via gRPC Catalog client, persists aggregate, and publishes OrderPlacedEvent through outbox. Event-driven saga consumes PaymentCompletedEvent, PaymentFailedEvent, and ShipmentDispatchedEvent with idempotent state-guard transitions and row-version concurrency retry. Includes wiring, CQRS repository split rules, file inventory, and open questions.
PaymentService saga and recovery flows docs/code-flows/paymentservice.md	Saga flow consumes OrderPlacedEvent, translates to ProcessPaymentCommand, charges via Stripe, publishes completion/failure events with handler-level idempotency via repository checks. HTTP admin endpoint reuses the same handler. Recovery sweeper background service finds stale Pending payments with distributed SQL locking, explicit transaction wrapping for entity update plus outbox persistence, and deterministic time handling.
ShippingService saga and query flows docs/code-flows/shippingservice.md	Saga consumes PaymentCompletedEvent, creates and dispatches shipment, publishes ShipmentDispatchedEvent with idempotency checks and aggregate state guards. Buyer-scoped query endpoint performs IDOR-safe ownership validation with "null → 404" behavior. Documents Shipment state machine, read/write repository split, and file inventory.
CatalogService read/write and reservation flows docs/code-flows/catalogservice.md	Cached HTTP reads use HybridCache two-tier lookup with stampede protection and negative caching. Seller-scoped HTTP writes include IDOR mismatch handling, xmin optimistic concurrency, and cache invalidation. Synchronous gRPC ReserveStock path invoked by OrderService includes concurrency conflict handling. Formalizes read/write split between domain write loaders and application read projections with diagrams and open questions on multi-replica L1 cache invalidation.
NotificationService event handling docs/code-flows/notificationservice.md	End-to-end event-to-email pipeline with three event-handler overloads converted to SendNotificationRequest, validated, and dispatched through INotificationSender. Explains design choices: consolidated single-class handlers, intentional absence of Domain folder and recipient-resolution abstraction. Includes file inventory and cross-references.

Sequence Diagram

sequenceDiagram
  participant Buyer
  participant OrderService
  participant CatalogService
  participant PaymentService
  participant ShippingService
  participant NotificationService
  Buyer->>OrderService: Place order (validate + reserve)
  OrderService->>CatalogService: ReserveStock (gRPC)
  CatalogService-->>OrderService: Stock reserved
  OrderService->>OrderService: Persist aggregate + outbox
  OrderService-->>Buyer: Order placed
  OrderService->>PaymentService: OrderPlacedEvent
  PaymentService->>PaymentService: Process payment (Stripe)
  PaymentService->>ShippingService: PaymentCompletedEvent
  ShippingService->>ShippingService: Create and dispatch shipment
  ShippingService->>NotificationService: ShipmentDispatchedEvent
  NotificationService->>Buyer: Send email

Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Docs/per service flow diagrams' directly relates to the changeset which adds per-service code-flow walkthroughs for five microservices, making it a clear and specific summary of the main change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/per-service-flow-diagrams

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/code-flows/catalogservice.md`:
- Line 270: Fix the grammar in the STATUS.md quoted sentence by changing “the
right move for ship multi-replica with reasonable consistency this sprint” to
“the right move to ship multi-replica with reasonable consistency this sprint”
(i.e., replace “for ship” with “to ship”) wherever that exact quote appears in
the docs/catalogservice.md excerpt or the STATUS.md source so the phrasing is
correct.

In `@docs/code-flows/orderservice.md`:
- Line 87: Update the doc text to reflect that idempotency is implemented by the
handler, not by the aggregate: replace claims that Order.MarkAsX methods no-op
on duplicate events with wording that the Wolverine consumer/handler (e.g.,
PaymentCompletedHandler) performs a status check and no-ops duplicate events,
while the Order aggregate methods (e.g., Order.MarkAsPaid()) enforce state via
throwing on invalid transitions; reference Order.MarkAsPaid() and
PaymentCompletedHandler status-check logic so readers understand the true
boundary of idempotency.

In `@docs/code-flows/paymentservice.md`:
- Line 155: The sentence listing “admin endpoints” as code that runs outside a
handler is too broad and conflicts with Flow 2; update the text around
AutoApplyTransactions/IMessageBus.PublishAsync/SaveChangesAsync to clarify that
only code paths which do not go through the Wolverine handler pipeline (i.e.,
truly external sweepers, cron jobs, or admin operations that call PublishAsync
directly without using bus.InvokeAsync) are outside the handler wrapper, and
explicitly note that admin endpoints routed through bus.InvokeAsync do enter the
handler pipeline and get the AutoApplyTransactions behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 83a770d2-3c60-4646-b1f6-06b2b9c3998e

📥 Commits

Reviewing files that changed from the base of the PR and between 8c75b70 and 48035ec.

📒 Files selected for processing (7)

• docs/STATUS.md
• docs/code-flows.md
• docs/code-flows/catalogservice.md
• docs/code-flows/notificationservice.md
• docs/code-flows/orderservice.md
• docs/code-flows/paymentservice.md
• docs/code-flows/shippingservice.md

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/code-flows/paymentservice.md (1)

198-198: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix the OrderService comparison — both services use the same pattern.

The claim that OrderService's Order.MarkAsX methods "no-op on duplicate transitions" contradicts the OrderService documentation (lines 87, 140 in orderservice.md), which clearly states that the aggregate methods throw on invalid transitions, while the handler does the no-op via status pre-checks. Both services actually follow the same layered pattern: handler-level idempotency (status/existence checks with early return) + aggregate-level invariants (throws on invalid state). The "Unlike" framing incorrectly implies a difference where none exists.

📝 Suggested fix

-**Idempotency by throw (not no-op).** Unlike OrderService's `Order.MarkAsX` methods (which no-op on duplicate transitions), `Payment.MarkAsCompleted` and `MarkAsFailed` **throw `InvalidOperationException`** if status is not `Pending`. The reason: PaymentService's idempotency lives at the *handler* level (existence check on `OrderId`), not the aggregate level. By the time you're calling `MarkAsX` here, you've already loaded a freshly-created `Pending` payment in the current request — a non-Pending status means a serious bug, not a duplicate event.
+**Idempotency at the handler level, invariants at the aggregate level.** Like OrderService's aggregate methods, `Payment.MarkAsCompleted` and `MarkAsFailed` **throw `InvalidOperationException`** on invalid transitions. PaymentService's idempotency lives at the *handler* level (existence check on `OrderId` that returns the existing payment ID early), not the aggregate level. By the time you're calling `MarkAsX` here, you've already loaded a freshly-created `Pending` payment in the current request — a non-Pending status means a serious bug (handler logic failure), not a duplicate event.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/code-flows/paymentservice.md` at line 198, The doc incorrectly states
OrderService's Order.MarkAsX methods "no-op on duplicate transitions" and frames
Payment.MarkAsCompleted/MarkAsFailed as different; update the wording to say
both services use the same pattern: handler-level idempotency (pre-checks/early
return in handlers) and aggregate-level invariants where Order.MarkAsX and
Payment.MarkAsCompleted/MarkAsFailed throw InvalidOperationException on invalid
transitions; remove the "Unlike" comparison and instead explicitly reference
Order.MarkAsX and Payment.MarkAsCompleted/MarkAsFailed to make the parity clear.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/code-flows/paymentservice.md`:
- Line 198: The doc incorrectly states OrderService's Order.MarkAsX methods
"no-op on duplicate transitions" and frames Payment.MarkAsCompleted/MarkAsFailed
as different; update the wording to say both services use the same pattern:
handler-level idempotency (pre-checks/early return in handlers) and
aggregate-level invariants where Order.MarkAsX and
Payment.MarkAsCompleted/MarkAsFailed throw InvalidOperationException on invalid
transitions; remove the "Unlike" comparison and instead explicitly reference
Order.MarkAsX and Payment.MarkAsCompleted/MarkAsFailed to make the parity clear.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 753b1f60-8514-486f-b5cd-bc1d0d93dd78

📥 Commits

Reviewing files that changed from the base of the PR and between 48035ec and 84c434f.

📒 Files selected for processing (3)

• docs/code-flows/catalogservice.md
• docs/code-flows/orderservice.md
• docs/code-flows/paymentservice.md