docs: add portable VSA vs Clean Architecture decision guide

[emeraldleaf]

Summary

A reusable, system-agnostic synthesis of the VSA-vs-Clean decision, distilled from a multi-turn architecture discussion. Written to be lifted into any project; NextAurora is the worked example at the end, not the premise. Same pattern as docs/messaging-transport-selection.md (#49) — portable reference knowledge, kept out of CLAUDE.md (which holds this repo's rules).

Core points it lands

• "Clean Architecture" is two things: the dependency rule (always-on, not earned, not in tension with VSA) and the 4-project structure (the only part with ceremony, the only part the "is it worth it?" question is actually about).
• VSA and Clean are orthogonal axes — organization/cohesion vs dependency direction. "Combine" = organize by feature + keep the domain decoupled.
• VSA doesn't auto-enforce the dependency rule — you enforce it on a spectrum: convention → architecture tests → project split. The middle rung (NetArchTest/ArchUnitNET) gives the same enforcement as the 4-project split without the ceremony, at the namespace level in a single project (code example included).
• Two meanings of "combine" — orthogonal axes + per-slice complexity gradient.
• Testcontainers shifted the calculus — integration-default for IO-touching code beats mock-heavy unit tests, which collapses the repository-interface-for-testability argument. But it's a Testing Trophy, not a pure rectangle — keep fast unit tests for pure domain logic; mind the Docker dependency + speed cost.
• The duplication tradeoff — cross-cutting concerns in pipeline behaviors (not per-slice), prefer duplication over the wrong abstraction; cost scales with slice count and bites hardest on pure CRUD.
• When-to-use table + common mistakes (incl. "don't add a repo interface per slice on EF Core," "don't 4-project-split just to get the dependency rule," "don't mix layered + sliced services in one solution").

Scope

• New doc: docs/vsa-vs-clean-architecture.md
• README Documentation table indexed
• No CLAUDE.md edit here — kept separate to avoid colliding with the open promotion-signal PR chore(claude): refine Clean promotion signal — dependency rule vs project split #50. The in-repo deep-dive pointer (CLAUDE.md "Promotion signal" → this guide) will be added on chore(claude): refine Clean promotion signal — dependency rule vs project split #50's branch.

Test plan

• Doc renders cleanly on GitHub (tables, code block, links)
• README index entry reads cleanly
• Cross-link from chore(claude): refine Clean promotion signal — dependency rule vs project split #50's promotion-signal section lands when that branch is updated

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a comprehensive architectural decision guide comparing Vertical Slice Architecture and Clean Architecture, clarifying dependency-rule vs. project-structure distinctions; outlines enforcement options (including architecture tests), tradeoffs and costs, modern integration-testing practices, guidance on handling duplication and cross-cutting concerns, common pitfalls, and a worked example demonstrating practical application.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e87fcde9-3ab7-4fd2-9ece-49f5c7919bf3

📥 Commits

Reviewing files that changed from the base of the PR and between 6d1a344 and f4f71bb.

📒 Files selected for processing (1)

• README.md

---

Walkthrough

This PR adds a new architecture decision guide documenting Vertical Slice Architecture (VSA) and Clean Architecture as orthogonal organizational and dependency concepts, with enforcement mechanisms, testing trade-offs, and a practical NextAurora example.

Changes

Architecture Decision Guide Documentation

Layer / File(s)	Summary
Core positioning and enforcement mechanisms README.md, docs/vsa-vs-clean-architecture.md	Reframes Clean Architecture into two separate concepts (dependency rule and multi-project layered structure), positions VSA and the dependency rule as orthogonal axes, and describes three enforcement rungs: convention/code review, architecture tests, and project splits. README updated with documentation index link.
Testing and duplication trade-offs docs/vsa-vs-clean-architecture.md	Discusses testing strategy shifts enabled by modern integration tooling (Testcontainers), favoring integration-default tests for IO-touching handlers over mock-heavy unit tests. Analyzes VSA's primary cost (cross-slice duplication) and describes when duplication is manageable through shared middleware/pipelines.
Decision matrix, common mistakes, and worked example docs/vsa-vs-clean-architecture.md	Provides "when to use which" guidance, lists common pitfalls (treating VSA and Clean as either/or, unnecessary repository wrappers for DB independence, over-applying integration tests to pure CRUD), and details NextAurora's applied structure: VSA folders with single-project enforcement via convention plus architecture tests, integration-default handler tests, and direct DbContext usage without repository wrappers.

🎯 1 (Trivial) | ⏱️ ~5 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 directly and clearly summarizes the main change: adding a new decision guide document contrasting VSA with Clean Architecture, which matches the primary content of the PR.
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/vsa-vs-clean-guide

---

_{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]

Caution

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

⚠️ Outside diff range comments (1)

docs/vsa-vs-clean-architecture.md (1)

1-205: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Propagate this new architecture pattern to canonical rule artifacts before merge.

This doc encodes reusable architecture-review patterns, but the required rule-propagation updates are missing from this PR (or an explicit deferral entry in docs/STATUS.md). Please sync the canonical governance files in the same change set or mark/document the deferral explicitly.

As per coding guidelines, "when encoding a pattern discovered via review, write to CLAUDE.md (most relevant section, new section only if no fit), .coderabbit.yaml path_instructions, .claude/agents/architecture-reviewer.md checklist, .claude/skills/ (if non-trivial multi-step), docs/STATUS.md (if deferred), and supporting docs (if the why deserves more than a one-liner)".

🤖 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/vsa-vs-clean-architecture.md` around lines 1 - 205, The PR added a
VSA-vs-Clean Architecture guide but didn’t propagate the pattern to our
canonical governance artifacts; update CLAUDE.md (add the new pattern into the
most relevant section or create a new section), add path_instructions in
.coderabbit.yaml to reference the new doc, extend
.claude/agents/architecture-reviewer.md checklist with the new enforcement
options (rung 1/2/3 and NetArchTest example), add any multi-step guidance under
.claude/skills/ if needed, and either record a clear deferral entry in
docs/STATUS.md or include explicit “deferred” notes in the above files per the
coding guidelines.

🤖 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/vsa-vs-clean-architecture.md`:
- Around line 1-205: The PR added a VSA-vs-Clean Architecture guide but didn’t
propagate the pattern to our canonical governance artifacts; update CLAUDE.md
(add the new pattern into the most relevant section or create a new section),
add path_instructions in .coderabbit.yaml to reference the new doc, extend
.claude/agents/architecture-reviewer.md checklist with the new enforcement
options (rung 1/2/3 and NetArchTest example), add any multi-step guidance under
.claude/skills/ if needed, and either record a clear deferral entry in
docs/STATUS.md or include explicit “deferred” notes in the above files per the
coding guidelines.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 83daed9a-a04b-4b32-aa23-a5e80798e3b6

📥 Commits

Reviewing files that changed from the base of the PR and between 6f340be and 6d1a344.

📒 Files selected for processing (2)

• README.md
• docs/vsa-vs-clean-architecture.md