Clarify CQRS guidance in BDR FAQ

[koriym]

Summary

• Reframe the BDR FAQ CQRS explanation around concern/model separation rather than repository placement.
• Clarify that BDR query objects are read-only projections and should not be saved back directly.
• Explain SQL as a natural projection mechanism and Query models as disposable read models.

Stacked PR

• Base branch: codex/docs-home-localization (Update documentation site navigation #100)
• This PR should be rebased onto 1.x after Update documentation site navigation #100 is merged.

Validation

• git diff --check
• jekyll build -s docs -d /tmp/ray-mediaquery-site

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f4c9cb17-90b4-4923-bcf6-f4c42f71ac21

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/clarify-bdr-cqrs-faq

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[koriym]

Posted by Claude (Claude Code) from @koriym's account.

Re-review — CQRS understanding & architectural framing

The update resolves both architectural concerns from the previous pass.

1. "BDR = thin CQRS Query side" tension → resolved.
Reframing it as "BDR fits the Query side of CQRS, but more precisely it is a rich read-model pattern", together with the explicit rule that the read model may carry derivation/presentation behavior (totals, labels, visibility, read-side priority) while state-changing invariants stay on the Command side, reconciles the FAQ with the body's rich domain objects (canProcess(), the injected rule engine). The canShowProcessAction() vs ProcessOrder split makes that boundary concrete.

2. Over-reaching beyond the library's scope → resolved.
"BDR does not define the Command model; Ray.MediaQuery can execute DML if that is the write mechanism you choose" draws the library boundary cleanly — the FAQ no longer implies the package owns a full CQRS write side it doesn't provide.

Practicality. "How do I save?" now leads with a concrete directive ("Use an explicit write path, not the BDR read object") and three actionable steps, restoring answer-first ergonomics for a how-to question.

CQRS accuracy. The new framing is correct: Command = business decision, Query = display structure; physical separation (separate DBs / infra / repository locations) is an optional implementation choice, not the essence. No new inaccuracies introduced.

Mechanical. All four files (EN/JA × root/docs/) carry the new text with parity; no stale orderCommandRepo / markAsProcessed identifiers remain; the earlier BDR パターン spacing nit is unified to BDRパターン in the body. The only remaining spaced variant is the JA front-matter title (docs/bdr-pattern-ja.md:3), which originates from #100 and is out of scope here.

LGTM.

[koriym]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[koriym]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.