@opengroundplan/core 0.1.1

package/templates/architectures/clean/files/src/__solutionName.dot__.Infrastructure/AssemblyMarker.cs

@@ -0,0 +1,10 @@
+using System.Reflection;
+
+namespace {{ solutionName | dot }}.Infrastructure;
+
+// Anchors this ring's assembly so the architecture fitness tests never depend on a
+// string assembly name that a rename would silently break.
+public static class AssemblyMarker
+{
+    public static Assembly Assembly => typeof(AssemblyMarker).Assembly;
+}

package/templates/architectures/clean/files/src/__solutionName.dot__.Infrastructure/External/.gitkeep

@@ -0,0 +1 @@
+# Adapters for everything outside the process: HTTP clients, queues, clocks, file systems.

package/templates/architectures/clean/files/src/__solutionName.dot__.Infrastructure/Persistence/.gitkeep

@@ -0,0 +1 @@
+# Repository and DbContext implementations of the Application ports.

package/templates/architectures/clean/files/src/__solutionName.dot__.Infrastructure/__solutionName.dot__.Infrastructure.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.Infrastructure</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Infrastructure</AssemblyName>
+  </PropertyGroup>
+
+  <!-- Driver and client packages live here and nowhere else. Add them to
+       Directory.Packages.props, then reference them without a Version. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/clean/files/src/__solutionName.snake__/application/__init__.py

@@ -0,0 +1 @@
+"""Application ring: the use cases, and the ports they need. Imports Domain only."""

package/templates/architectures/clean/files/src/__solutionName.snake__/application/ports/__init__.py

@@ -0,0 +1 @@
+"""Ports: Protocol classes the use cases depend on. Implemented in Infrastructure."""

package/templates/architectures/clean/files/src/__solutionName.snake__/application/use_cases/__init__.py

@@ -0,0 +1 @@
+"""One module per use case, one entry point each. This is what the system does."""

package/templates/architectures/clean/files/src/__solutionName.snake__/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain ring: entities, value objects, domain events. Imports nothing from this package."""

package/templates/architectures/clean/files/src/__solutionName.snake__/domain/entities/__init__.py

@@ -0,0 +1 @@
+"""Entities and aggregates. Plain Python — no framework types, no ORM base classes."""

package/templates/architectures/clean/files/src/__solutionName.snake__/domain/events/__init__.py

@@ -0,0 +1 @@
+"""Domain events. Named in the past tense, carrying only domain types."""

package/templates/architectures/clean/files/src/__solutionName.snake__/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure ring: adapters implementing the Application ports."""

package/templates/architectures/clean/files/src/__solutionName.snake__/infrastructure/external/__init__.py

@@ -0,0 +1 @@
+"""Adapters for everything outside the process: HTTP clients, queues, clocks."""

package/templates/architectures/clean/files/src/__solutionName.snake__/infrastructure/persistence/__init__.py

@@ -0,0 +1 @@
+"""Repository implementations. The only place that knows the storage technology."""

package/templates/architectures/clean/files/src/application/ports/README.md

@@ -0,0 +1 @@
+<!-- Ports: the interfaces the use cases need. Declared here, implemented in ../../infrastructure. -->

package/templates/architectures/clean/files/src/application/use-cases/README.md

@@ -0,0 +1 @@
+<!-- One module per use case, one entry point each. This is what the system does. -->

package/templates/architectures/clean/files/src/domain/README.md

@@ -0,0 +1 @@
+<!-- Entities, value objects and domain events. Imports nothing from outside this folder. -->

package/templates/architectures/clean/files/src/infrastructure/README.md

@@ -0,0 +1 @@
+<!-- Adapters implementing the Application ports: persistence, HTTP clients, clocks, queues. -->

package/templates/architectures/clean/files/tests/__solutionName.dot__.ArchitectureTests/DependencyRuleTests.cs

@@ -0,0 +1,118 @@
+using System.Reflection;
+using Xunit;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+// The Dependency Rule, enforced at assembly granularity — in .NET a ring is a project.
+public sealed class DependencyRuleTests
+{
+    // Ring names are this architecture's definition, not configuration.
+    private const string Domain = "Domain";
+    private const string Application = "Application";
+    private const string Infrastructure = "Infrastructure";
+    private static readonly string[] WebRing = ["Api", "Web", "AppHost"];
+
+    // Both spellings: a base may name the web project Acme.Billing.Api or AcmeBilling.Api.
+    private static readonly string[] Prefixes = ["{{ solutionName | dot }}", "{{ solutionName | pascal }}"];
+
+    // Delivery and persistence frameworks live outside the core. A reference from an inner ring
+    // means business logic learned about a mechanism.
+    private static readonly string[] FrameworksBannedInCore =
+    [
+        "Microsoft.AspNetCore",
+        "Microsoft.EntityFrameworkCore",
+        "Microsoft.Extensions.Hosting",
+    ];
+
+    [Fact]
+    public void Domain_knows_nothing_further_out()
+    {
+        var assembly = global::{{ solutionName | dot }}.Domain.AssemblyMarker.Assembly;
+        AssertNoOuterRingReference(assembly, [Application, Infrastructure, .. WebRing]);
+        AssertNoFrameworkReference(assembly);
+        AssertProjectFileHasNoOuterRingReference(Domain, [Application, Infrastructure, .. WebRing]);
+    }
+
+    [Fact]
+    public void Application_depends_on_Domain_and_nothing_else()
+    {
+        var assembly = global::{{ solutionName | dot }}.Application.AssemblyMarker.Assembly;
+        AssertNoOuterRingReference(assembly, [Infrastructure, .. WebRing]);
+        AssertNoFrameworkReference(assembly);
+        AssertProjectFileHasNoOuterRingReference(Application, [Infrastructure, .. WebRing]);
+    }
+
+    [Fact]
+    public void Infrastructure_never_reaches_the_web_ring()
+    {
+        AssertNoOuterRingReference(global::{{ solutionName | dot }}.Infrastructure.AssemblyMarker.Assembly, WebRing);
+        AssertProjectFileHasNoOuterRingReference(Infrastructure, WebRing);
+    }
+
+    private static void AssertNoOuterRingReference(Assembly assembly, string[] forbiddenRings)
+    {
+        var violations = ReferencedNames(assembly)
+            .Where(name => forbiddenRings.Any(ring => IsRing(name, ring)))
+            .ToArray();
+
+        Assert.True(
+            violations.Length == 0,
+            $"{assembly.GetName().Name} references an outer ring: {string.Join(", ", violations)}");
+    }
+
+    private static void AssertNoFrameworkReference(Assembly assembly)
+    {
+        var violations = ReferencedNames(assembly)
+            .Where(name => FrameworksBannedInCore.Any(banned => name.StartsWith(banned, StringComparison.Ordinal)))
+            .ToArray();
+
+        Assert.True(
+            violations.Length == 0,
+            $"{assembly.GetName().Name} is core and may not reference: {string.Join(", ", violations)}");
+    }
+
+    // Metadata lists only references the compiler saw used, so an unused-but-declared
+    // ProjectReference would slip past the assembly check. The csproj closes that gap.
+    private static void AssertProjectFileHasNoOuterRingReference(string ring, string[] forbiddenRings)
+    {
+        var file = RingProjectFile(ring);
+        var contents = File.ReadAllText(file);
+
+        var violations = forbiddenRings
+            .Where(outer => Prefixes.Any(prefix => contents.Contains($"{prefix}.{outer}.csproj", StringComparison.Ordinal)))
+            .ToArray();
+
+        Assert.True(
+            violations.Length == 0,
+            $"{Path.GetFileName(file)} declares a ProjectReference to: {string.Join(", ", violations)}");
+    }
+
+    private static IEnumerable<string> ReferencedNames(Assembly assembly) =>
+        assembly.GetReferencedAssemblies().Select(reference => reference.Name ?? string.Empty);
+
+    private static bool IsRing(string assemblyName, string ring) =>
+        Prefixes.Any(prefix => assemblyName == $"{prefix}.{ring}");
+
+    private static string RingProjectFile(string ring)
+    {
+        var source = Path.Combine(RepositoryRoot(), "src");
+        var matches = Directory.GetFiles(source, $"*.{ring}.csproj", SearchOption.AllDirectories);
+
+        Assert.True(matches.Length == 1, $"expected one *.{ring}.csproj under {source}, found {matches.Length}");
+        return matches[0];
+    }
+
+    // Walk up from the test binary to the directory holding src/, so no path is baked in.
+    private static string RepositoryRoot()
+    {
+        for (var directory = new DirectoryInfo(AppContext.BaseDirectory); directory is not null; directory = directory.Parent)
+        {
+            if (Directory.Exists(Path.Combine(directory.FullName, "src")))
+            {
+                return directory.FullName;
+            }
+        }
+
+        throw new DirectoryNotFoundException($"No ancestor of {AppContext.BaseDirectory} contains a src/ directory.");
+    }
+}

package/templates/architectures/clean/files/tests/__solutionName.dot__.ArchitectureTests/__solutionName.dot__.ArchitectureTests.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <!-- xUnit v3 test projects are executables. -->
+    <OutputType>Exe</OutputType>
+    <RootNamespace>{{ solutionName | dot }}.ArchitectureTests</RootNamespace>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- CA1707 polices public API naming; underscored test names are the convention here. -->
+    <NoWarn>$(NoWarn);CA1707</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+  </ItemGroup>
+
+  <!-- References every ring on purpose: a test cannot assert on an assembly it cannot load. -->
+  <ItemGroup>
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Domain/{{ solutionName | dot }}.Domain.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Infrastructure/{{ solutionName | dot }}.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/cqrs/blueprint.yaml

@@ -0,0 +1,134 @@
+id: cqrs
+kind: architecture
+name: CQRS (Command Query Responsibility Segregation)
+description: >-
+  Folder overlay that splits one bounded context into a command side that goes through a domain
+  model and a query side that reads the store directly, plus a boundary check per stack that
+  fails when the query side reaches for a command-side aggregate.
+
+tags:
+  - cqrs
+  - commands
+  - queries
+  - read-models
+  - bounded-context
+  - boundaries
+  - fitness-function
+
+# Nothing: the overlay contributes structure and one check, and composes onto any base whose
+# supportsArchitectures lists `cqrs`.
+requires: []
+
+# A rival application-layout overlay declares the conflict from its own side — naming an id
+# that does not exist yet makes the whole catalog fail to load, and the resolver accepts one
+# architecture per run regardless.
+conflicts: []
+
+# Capability names, so a CI or agent-kit layer can key off "this repo has a boundary gate"
+# instead of naming this blueprint.
+provides:
+  - architecture-layout
+  - boundary-check
+  - command-query-split
+
+supportsArchitectures: []
+
+variables:
+  # Fowler scopes CQRS to a BoundedContext, never to a whole system. Naming the context is what
+  # keeps the layout from sprouting a commands/ and queries/ folder at the repo root.
+  - name: contextName
+    prompt: The bounded context this split applies to (e.g. "ordering")
+    type: string
+    default: ordering
+    required: false
+
+# import-linter is declared in files/pyproject.toml, so nothing here needs to know the package
+# manager — dropping that question keeps the interview to the one answer this overlay uses.
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  # Not docs/ARCHITECTURE.md: the agent-kit owns that path and writes it after this overlay,
+  # so sharing it would be a plan-time conflict rather than an append. One doc serves node and
+  # typescript because the two stacks get an identical layout and an identical check.
+  - from: files/docs/architecture/cqrs.dotnet.md
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/docs/architecture/cqrs.node.md
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/docs/architecture/cqrs.python.md
+    to: .
+    when: "stack == 'python'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # A side of the split is a project here, which is why the fitness test can assert on assembly
+  # references. The one glob covers Abstractions and all three context projects, since every
+  # directory name starts with the solution's dotted prefix.
+  - from: files/src/__solutionName.dot__.*/**
+    to: .
+    when: "stack == 'dotnet'"
+  # Fixed folder name so `dotnet sln add tests/ArchitectureTests` resolves without a glob, and so
+  # it never collides with the testing-unit layer's .Tests project.
+  - from: files/tests/ArchitectureTests/*
+    to: .
+    when: "stack == 'dotnet'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  # `__init__` has no matching variable, so plan warns that it was left literal. That is the
+  # engine reporting a real Python filename, not a defect — see tokens.renderPath.
+  - from: files/src/__solutionName.snake__/__contextName.snake__/**/__init__.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  # Declared, not installed by a post-apply step: a package added after generation is missing
+  # from the first install (ADR 0005, spec 003). The contract file is useless without the linter.
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+  # ── node / typescript ───────────────────────────────────────────────────────
+  # The checker reads roles off path segments, so a second bounded context beside this one
+  # needs no configuration change.
+  - from: files/src/__contextName.kebab__/**/*.ts
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/scripts/check-cqrs-boundaries.mjs
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/eslint.config.cqrs.mjs
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # One step, no glob: the .NET CLI does not expand one, and `--include-references` (on by
+  # default) walks the test project's references to pull all four src projects in with it.
+  # Required — without it `dotnet build` and `dotnet test` never see the split or its check.
+
+  # The API project is the composition root — the only place allowed to see both sides. Its
+  # folder name is base-dependent, so this one needs a glob and only runs on a POSIX shell;
+  # docs/architecture/cqrs.dotnet.md carries it for a manual run.
+  - run: dotnet add src/*.Api/*.csproj reference src/*.Commands/*.csproj src/*.Queries/*.csproj
+    when: "stack == 'dotnet'"
+    optional: true
+
+  - run: npm pkg set "scripts.check:cqrs"="node scripts/check-cqrs-boundaries.mjs"
+    when: "stack == 'node' || stack == 'typescript'"
+    optional: true

package/templates/architectures/cqrs/files/.importlinter

@@ -0,0 +1,26 @@
+# Boundary enforcement for the command/query split. Run with `lint-imports`;
+# a violated contract exits non-zero, so wire it into CI next to the linter.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:query-side-is-independent]
+name = The query side does not import the command side
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.{{ contextName | snake }}.queries
+    {{ solutionName | snake }}.{{ contextName | snake }}.read_models
+forbidden_modules =
+    {{ solutionName | snake }}.{{ contextName | snake }}.domain
+    {{ solutionName | snake }}.{{ contextName | snake }}.commands
+# A query needing an aggregate is a read model that has not been written yet.
+
+[importlinter:contract:command-side-ignores-projections]
+name = The command side does not read from a projection
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.{{ contextName | snake }}.domain
+    {{ solutionName | snake }}.{{ contextName | snake }}.commands
+forbidden_modules =
+    {{ solutionName | snake }}.{{ contextName | snake }}.queries
+    {{ solutionName | snake }}.{{ contextName | snake }}.read_models
+# Projections are stale by construction; a decision made from one is made on stale data.

package/templates/architectures/cqrs/files/Directory.Packages.props

@@ -0,0 +1,7 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/architectures/cqrs/files/__solutionName.dot__.slnx

@@ -0,0 +1,11 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Abstractions/{{ solutionName | dot }}.Abstractions.csproj" />
+    <Project Path="src/{{ solutionName | dot }}.{{ contextName | pascal }}.Commands/{{ solutionName | dot }}.{{ contextName | pascal }}.Commands.csproj" />
+    <Project Path="src/{{ solutionName | dot }}.{{ contextName | pascal }}.Domain/{{ solutionName | dot }}.{{ contextName | pascal }}.Domain.csproj" />
+    <Project Path="src/{{ solutionName | dot }}.{{ contextName | pascal }}.Queries/{{ solutionName | dot }}.{{ contextName | pascal }}.Queries.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/ArchitectureTests/ArchitectureTests.csproj" />
+  </Folder>
+</Solution>

package/templates/architectures/cqrs/files/docs/architecture/cqrs.dotnet.md

@@ -0,0 +1,116 @@
+# CQRS — {{ solutionName | title }} (.NET)
+
+> Use a different model to update information than the model you use to read it.
+> — Martin Fowler, [*CQRS*](https://martinfowler.com/bliki/CQRS.html)
+
+That sentence is the whole pattern. Everything below is a consequence of it.
+
+## The one rule
+
+> **The query side may not reference the command side.**
+
+A query handler that loads an aggregate to build a DTO has re-merged the two models and
+deleted the only benefit this pattern offers. If a query needs data an aggregate holds, the
+answer is a new read model, not a reference.
+
+Here the rule is a compile-time fact: the `.Queries` project has no `ProjectReference` to
+`.Domain` or `.Commands`, so those types are not on the query side's compiler surface at all.
+
+## Layout
+
+CQRS is scoped to **one bounded context** — `{{ contextName | title }}` — not to the solution.
+Fowler is explicit that it "should only be used on specific portions of a system (a
+BoundedContext) and not the system as a whole." Other contexts stay plain CRUD until one of
+them earns the split.
+
+```
+src/
+  {{ solutionName | dot }}.Abstractions/
+      ICommandHandler.cs        ICommand, ICommandHandler<T>
+      IQueryHandler.cs          IQuery<T>, IQueryHandler<T,R>
+  {{ solutionName | dot }}.{{ contextName | pascal }}.Domain/
+      Aggregates/               the write model — references nothing
+  {{ solutionName | dot }}.{{ contextName | pascal }}.Commands/
+      Handlers/                 one per task; loads an aggregate, calls it, saves it
+  {{ solutionName | dot }}.{{ contextName | pascal }}.Queries/
+      Handlers/                 one per screen; SQL straight into a ReadModels record
+      ReadModels/               DTOs with no behaviour
+tests/
+  ArchitectureTests/            fixed folder name; assembly is {{ solutionName | dot }}.ArchitectureTests
+```
+
+| Project suffix | Holds | May reference |
+|---|---|---|
+| `.Abstractions` | The four handler contracts | nothing |
+| `.Domain` | Aggregates and their invariants — the write model | nothing |
+| `.Commands` | One handler per task | `.Domain`, `.Abstractions` |
+| `.Queries` | One handler per screen, plus its read models | `.Abstractions` |
+
+## Commands return nothing
+
+`ICommandHandler<TCommand>` returns `Task`, not `Task<TResult>`. The compiler enforces this,
+not review: a handler that wants to return a projection cannot. Generate ids on the caller so
+a command never needs a return value to hand one back.
+
+Name commands after the task the user performs — `BookHotelRoom`, not `SetReservationStatus`.
+A command named after a field is a CRUD update that learned new vocabulary.
+
+## You do not need a second database
+
+Azure documents "separate models in a single data store" as the **foundational** level of this
+pattern, and that is what this layout gives you: both sides talk to the same store, the write
+side through aggregates, the read side through SQL. There is no eventual consistency here and
+nothing to synchronize.
+
+Splitting the *stores* is a separate, much larger decision. It buys eventual consistency for
+your entire UX, and you must then design every screen for users acting on stale data. Do that
+only when you have measured the asymmetry that justifies it.
+
+You also do not need event sourcing. Fowler: *"Strictly CQRS isn't really about events."*
+
+## The boundary check
+
+Run `dotnet test`. `tests/ArchitectureTests` uses reflection over assembly references plus a
+csproj scan, and four fitness tests fail the build:
+
+1. **Query side never reaches the command side** — no assembly reference and no
+   `ProjectReference` from `.Queries` to `.Domain` or `.Commands`.
+2. **Command side goes through the domain model** — `.Commands` *must* reference `.Domain`.
+   Without this the command path is CRUD wearing the pattern's vocabulary, and no negative
+   test would ever catch it.
+3. **Command side never reads from a projection** — no reference from `.Commands` to `.Queries`.
+4. **Write model depends on neither side** — `.Domain` references nothing.
+
+The csproj scan exists because assembly metadata lists only references the compiler saw *used*;
+an unused-but-declared `ProjectReference` would otherwise slip past.
+
+Wire `dotnet test` into CI. A check that only runs locally is a check that does not run.
+
+## What is not enforced mechanically
+
+Real rules with no automated gate. These are review's job:
+
+- **Commands are task-shaped.** Nothing can tell `SetReservationStatus` from `BookHotelRoom`.
+- **The split stays inside one context.** Adding `.Commands`/`.Queries` projects for every
+  context is the documented way this pattern fails, and nothing here prevents it.
+- **Read models are per-screen, not shared.** One `OrderDto` reused by six screens is a
+  canonical model growing back.
+
+## Adding a project later
+
+Every generated project is already in the `.slnx` and wired to its neighbours, so a fresh
+clone builds and tests with no wiring step. A project you add yourself needs one line:
+
+```
+dotnet sln add src/YourSolution.Ordering.Reporting/YourSolution.Ordering.Reporting.csproj
+```
+
+The API project references **both** sides — it is the composition root, and the only place
+allowed to see them together.
+
+## Sources
+
+- Martin Fowler, [*CQRS*](https://martinfowler.com/bliki/CQRS.html) — the definition, the
+  BoundedContext scoping, and the productivity warning.
+- Microsoft Learn, [*CQRS pattern*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs)
+  — the single-store foundational level, and when not to use the pattern at all.

package/templates/architectures/cqrs/files/docs/architecture/cqrs.node.md

@@ -0,0 +1,117 @@
+# CQRS — {{ solutionName | title }}
+
+Applies to the `node` and `typescript` stacks. Current stack: `{{ stack }}`.
+
+> Use a different model to update information than the model you use to read it.
+> — Martin Fowler, [*CQRS*](https://martinfowler.com/bliki/CQRS.html)
+
+That sentence is the whole pattern. Everything below is a consequence of it.
+
+## The one rule
+
+> **The query side may not import the command side.**
+
+A query handler that loads an aggregate to build a DTO has re-merged the two models and
+deleted the only benefit this pattern offers. If a query needs data an aggregate holds, the
+answer is a new read model, not an import.
+
+## Layout
+
+CQRS is scoped to **one bounded context** — `{{ contextName | title }}` — not to the repo.
+Fowler is explicit that it "should only be used on specific portions of a system (a
+BoundedContext) and not the system as a whole." Other areas stay plain CRUD until one of them
+earns the split.
+
+```
+src/{{ contextName | kebab }}/
+  domain/          aggregates and their invariants — the write model
+  commands/        one handler per task; loads an aggregate, calls it, saves it
+  queries/         one handler per screen; SQL straight into a read model
+  read-models/     DTOs with no behaviour, one shape per screen
+scripts/check-cqrs-boundaries.mjs
+eslint.config.cqrs.mjs
+```
+
+| Folder | Holds | May import |
+|---|---|---|
+| `domain/` | Aggregates — the write model | nothing from the other three |
+| `commands/` | One handler per task | `domain/` |
+| `queries/` | One handler per screen | `read-models/` |
+| `read-models/` | Per-screen DTOs | nothing from the other three |
+
+Adding a second context means a second folder beside this one with the same four children.
+The check reads these names as path segments, so it keeps working with no configuration.
+
+## Commands return nothing
+
+`CommandHandler<TCommand>` resolves to `Promise<void>`. A command that returns data has become
+a query. Generate ids on the caller so a command never needs a return value to hand one back.
+
+Name commands after the task the user performs — `BookHotelRoom`, not `SetReservationStatus`.
+A command named after a field is a CRUD update that learned new vocabulary.
+
+## You do not need a second database
+
+Azure documents "separate models in a single data store" as the **foundational** level of this
+pattern, and that is what this layout gives you: both sides talk to the same store, the write
+side through aggregates, the read side through SQL. There is no eventual consistency here and
+nothing to synchronize.
+
+Splitting the *stores* is a separate, much larger decision. It buys eventual consistency for
+your entire UX, and you must then design every screen for users acting on stale data. Do that
+only when you have measured the asymmetry that justifies it.
+
+You also do not need event sourcing. Fowler: *"Strictly CQRS isn't really about events."*
+
+## The boundary check
+
+Run `npm run check:cqrs`. `scripts/check-cqrs-boundaries.mjs` is zero-dependency, resolves
+relative imports, and exits non-zero on two rules:
+
+1. **The query side may not import the command side** — nothing under `queries/` or
+   `read-models/` may import `domain/` or `commands/`.
+2. **The command side may not read a projection** — nothing under `domain/` or `commands/` may
+   import `queries/` or `read-models/`. Projections are stale by construction; a decision made
+   from one is a decision made on stale data.
+
+`eslint.config.cqrs.mjs` mirrors rule 1 in the editor via `no-restricted-imports`. Spread it
+into your ESLint config:
+
+```js
+import cqrs from './eslint.config.cqrs.mjs';
+export default [...cqrs, /* the rest of your config */];
+```
+
+The script stays the authority — it needs no linter, and the bases disagree on whether that is
+ESLint or Biome. Wire `npm run check:cqrs` into CI next to lint.
+
+### Overriding the folder names
+
+The script reads its segments from the environment, so a repo that spells them differently does
+not have to fork it: `CQRS_SOURCE_DIR`, `CQRS_DOMAIN_SEGMENT`, `CQRS_COMMANDS_SEGMENT`,
+`CQRS_QUERIES_SEGMENT`, `CQRS_READ_MODELS_SEGMENT`, `CQRS_EXTENSIONS`.
+
+## What is not enforced mechanically
+
+Real rules with no automated gate. These are review's job:
+
+- **Commands are task-shaped.** Nothing can tell `SetReservationStatus` from `BookHotelRoom`.
+- **Commands do not return data.** The types say `Promise<void>`, but plain JS and a handler
+  typed as `any` slip past. TypeScript catches this; the `node` stack does not.
+- **The split stays inside one context.** Sprouting `commands/`/`queries/` everywhere is the
+  documented way this pattern fails, and nothing here prevents it.
+- **Read models are per-screen, not shared.** One `OrderDto` reused by six screens is a
+  canonical model growing back.
+
+## Manual wiring, if the post-apply step was skipped
+
+```
+npm pkg set "scripts.check:cqrs"="node scripts/check-cqrs-boundaries.mjs"
+```
+
+## Sources
+
+- Martin Fowler, [*CQRS*](https://martinfowler.com/bliki/CQRS.html) — the definition, the
+  BoundedContext scoping, and the productivity warning.
+- Microsoft Learn, [*CQRS pattern*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs)
+  — the single-store foundational level, and when not to use the pattern at all.