@jeffrey2423/coding-standards 1.0.0 → 2.0.0

package/bin/cli.js

@@ -1,35 +1,388 @@
 #!/usr/bin/env node
 
+// Interactive installer for the coding-standards library.
+// Lets the user pick exactly the standards their project needs (by platform /
+// architecture) and copies only those into ./coding-standards, then generates
+// an INDEX.md so AI coding agents know which standards are active.
+
 const fs = require("fs");
 const path = require("path");
 
-const standardsDir = path.join(__dirname, "..", "standards");
-const targetDir = path.join(process.cwd(), "coding-standards");
+const STANDARDS_DIR = path.join(__dirname, "..", "standards");
+const TARGET_DIR = path.join(process.cwd(), "coding-standards");
+const MANIFEST = path.join(TARGET_DIR, ".standards-manifest.json");
 
-const files = fs
-  .readdirSync(standardsDir)
-  .filter((f) => f.endsWith(".md"));
+// The exact flat file set shipped by v1.x. Used to clean up a v1 install on
+// upgrade without touching the user's own root-level files.
+const LEGACY_V1_FILES = new Set([
+  "architecture-patterns.md",
+  "backend-standards.md",
+  "database-conventions.md",
+  "frontend-standards.md",
+  "mobile-flutter-standards.md",
+  "mobile-react-native-standards.md",
+  "technical-preferences-ux.md",
+  "technology-stack.md",
+  "vite-config-standard.md",
+]);
 
-if (files.length === 0) {
-  console.error("No standard files found in package.");
-  process.exit(1);
+// ── Selectable architecture docs (backend, opt-in) ───────────────────────────
+const ARCH_DOCS = [
+  { id: "anatomy", file: "microservice-anatomy.md", label: "Microservice anatomy (layers, events)" },
+  { id: "multitenancy", file: "multitenancy.md", label: "Multi-tenancy (RLS, tenant catalog)" },
+  { id: "events", file: "event-driven.md", label: "Event-driven (outbox, sagas)" },
+  { id: "api", file: "public-api-facade.md", label: "Public API facade (gateway, webhooks)" },
+  { id: "shared", file: "shared-vs-owned.md", label: "Shared vs owned components" },
+];
+
+// ── Resolve which directories/files to copy from a selection ─────────────────
+function resolveSources(sel) {
+  const sources = []; // { from: absolute path, to: relative path under coding-standards }
+
+  // core is always included
+  sources.push({ dir: "core" });
+
+  if (sel.backend) {
+    // base backend docs
+    for (const f of ["backend-standards.md", "technology-stack.md", "database-conventions.md"]) {
+      sources.push({ file: path.join("backend", f) });
+    }
+    // opt-in architecture docs
+    for (const a of ARCH_DOCS) {
+      if (sel.arch.includes(a.id)) {
+        sources.push({ file: path.join("backend", "architecture", a.file) });
+      }
+    }
+  }
+
+  if (sel.web) {
+    sources.push({ dir: path.join("web", "_base") });
+    sources.push({ dir: path.join("web", sel.web) }); // spa | single-spa | microfrontends
+  }
+
+  for (const fw of sel.mobile) {
+    sources.push({ dir: path.join("mobile", fw) }); // flutter | react-native
+  }
+
+  return sources;
+}
+
+// ── Copy helpers ─────────────────────────────────────────────────────────────
+function listMarkdown(absDir) {
+  const out = [];
+  for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
+    const abs = path.join(absDir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(abs));
+    else if (entry.name.endsWith(".md")) out.push(abs);
+  }
+  return out;
+}
+
+function copyFile(absFrom) {
+  const rel = path.relative(STANDARDS_DIR, absFrom);
+  const dest = path.join(TARGET_DIR, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(absFrom, dest);
+  return rel.split(path.sep).join("/");
+}
+
+function copySources(sources) {
+  const copied = [];
+  for (const s of sources) {
+    if (s.dir) {
+      const abs = path.join(STANDARDS_DIR, s.dir);
+      if (!fs.existsSync(abs)) continue;
+      for (const f of listMarkdown(abs)) copied.push(copyFile(f));
+    } else if (s.file) {
+      const abs = path.join(STANDARDS_DIR, s.file);
+      if (!fs.existsSync(abs)) continue;
+      copied.push(copyFile(abs));
+    }
+  }
+  return [...new Set(copied)].sort();
+}
+
+// ── Upgrade / re-run cleanup ─────────────────────────────────────────────────
+// Remove files this installer created on a previous run (tracked in the
+// manifest) plus any v1 flat-layout leftovers, so upgrading from v1 or changing
+// the selection never leaves stale, contradictory standards behind. Files the
+// installer doesn't own are never touched.
+function cleanPreviousInstall() {
+  if (!fs.existsSync(TARGET_DIR)) return { removed: 0, legacy: 0 };
+  let removed = 0;
+  let legacy = 0;
+
+  // 1. Files tracked by a previous v2 run.
+  if (fs.existsSync(MANIFEST)) {
+    try {
+      const prev = JSON.parse(fs.readFileSync(MANIFEST, "utf8"));
+      for (const rel of prev.files || []) {
+        const abs = path.join(TARGET_DIR, rel);
+        if (fs.existsSync(abs)) { fs.rmSync(abs); removed++; }
+      }
+    } catch {
+      /* corrupt manifest — fall through to legacy detection */
+    }
+  }
+
+  // 2. v1 leftovers: remove only the exact flat files v1 shipped — never the
+  //    user's own root-level markdown.
+  for (const entry of fs.readdirSync(TARGET_DIR, { withFileTypes: true })) {
+    if (entry.isFile() && LEGACY_V1_FILES.has(entry.name)) {
+      fs.rmSync(path.join(TARGET_DIR, entry.name));
+      legacy++;
+    }
+  }
+
+  pruneEmptyDirs(TARGET_DIR);
+  return { removed, legacy };
+}
+
+function pruneEmptyDirs(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sub = path.join(dir, entry.name);
+    pruneEmptyDirs(sub);
+    if (fs.readdirSync(sub).length === 0) fs.rmdirSync(sub);
+  }
+}
+
+function writeManifest(copied, sel) {
+  const data = {
+    version: require("../package.json").version,
+    selection: describeSelection(sel),
+    files: copied,
+  };
+  fs.writeFileSync(MANIFEST, JSON.stringify(data, null, 2) + "\n");
+}
+
+// ── Front-matter parsing for INDEX generation ────────────────────────────────
+function readFrontMatter(relPath) {
+  const abs = path.join(TARGET_DIR, relPath);
+  const text = fs.readFileSync(abs, "utf8");
+  const m = text.match(/^---\s*([\s\S]*?)\s*---/);
+  const fm = { title: "", load_when: "" };
+  if (m) {
+    for (const line of m[1].split("\n")) {
+      const t = line.match(/^title:\s*(.+)$/);
+      const l = line.match(/^load_when:\s*"?(.+?)"?\s*$/);
+      if (t) fm.title = t[1].trim();
+      if (l) fm.load_when = l[1].trim();
+    }
+  }
+  if (!fm.title) {
+    // fall back to first H1 or filename
+    const h1 = text.match(/^#\s+(.+)$/m);
+    fm.title = h1 ? h1[1].trim() : path.basename(relPath, ".md");
+  }
+  return fm;
+}
+
+function generateIndex(copied, sel) {
+  const lines = [];
+  lines.push("# Coding Standards — Active Set");
+  lines.push("");
+  lines.push("> Generated by `@jeffrey2423/coding-standards`. These are the standards active in THIS project.");
+  lines.push("> AI agents: read this first, then load a standard on demand per its **Load when** trigger.");
+  lines.push("");
+  lines.push(`Selection: ${describeSelection(sel)}`);
+  lines.push("");
+  lines.push("| Standard | File | Load when |");
+  lines.push("|---|---|---|");
+  for (const rel of copied) {
+    const fm = readFrontMatter(rel);
+    const lw = fm.load_when || "—";
+    lines.push(`| ${fm.title} | \`${rel}\` | ${lw} |`);
+  }
+  lines.push("");
+  lines.push("## Precedence");
+  lines.push("");
+  lines.push("- A more specific platform/track doc overrides a general one.");
+  lines.push("- `MUST` overrides `SHOULD`. Surface real conflicts to the user instead of guessing.");
+  lines.push("");
+  fs.writeFileSync(path.join(TARGET_DIR, "INDEX.md"), lines.join("\n"));
+}
+
+function describeSelection(sel) {
+  const parts = [];
+  if (sel.backend) parts.push(`backend (arch: ${sel.arch.length ? sel.arch.join(", ") : "none"})`);
+  if (sel.web) parts.push(`web/${sel.web}`);
+  if (sel.mobile.length) parts.push(`mobile/${sel.mobile.join("+")}`);
+  return parts.length ? parts.join("; ") : "core only";
+}
+
+// ── Flag parsing (non-interactive mode) ──────────────────────────────────────
+function parseFlags(argv) {
+  const flags = {};
+  for (const arg of argv) {
+    if (!arg.startsWith("--")) continue;
+    const [k, v] = arg.slice(2).split("=");
+    flags[k] = v === undefined ? true : v;
+  }
+  return flags;
+}
+
+function selectionFromFlags(flags) {
+  const all = flags.all === true;
+  const sel = { backend: false, web: null, mobile: [], arch: [] };
+
+  if (all) {
+    sel.backend = true;
+    sel.web = "microfrontends";
+    sel.mobile = ["flutter", "react-native"];
+    sel.arch = ARCH_DOCS.map((a) => a.id);
+    return sel;
+  }
+
+  if (flags.backend) sel.backend = true;
+  if (typeof flags.web === "string") sel.web = flags.web;
+  else if (flags.web === true) sel.web = "spa";
+  if (typeof flags.mobile === "string") sel.mobile = flags.mobile.split(",").map((s) => s.trim());
+
+  if (sel.backend) {
+    if (flags["no-arch"]) sel.arch = [];
+    else if (typeof flags.arch === "string" && flags.arch !== "all") {
+      sel.arch = flags.arch.split(",").map((s) => s.trim()).filter((id) => ARCH_DOCS.some((a) => a.id === id));
+    } else {
+      sel.arch = ARCH_DOCS.map((a) => a.id); // default: all
+    }
+  }
+  return sel;
+}
+
+function hasPlatformFlag(flags) {
+  return flags.all || flags.backend || flags.web !== undefined || flags.mobile !== undefined;
+}
+
+// ── Interactive mode (@clack/prompts) ────────────────────────────────────────
+async function interactive() {
+  const p = await import("@clack/prompts");
+  p.intro("📐 coding-standards — pick what your project needs");
+
+  const platforms = await p.multiselect({
+    message: "What are you building? (space to toggle, enter to confirm)",
+    options: [
+      { value: "backend", label: "Backend / API (.NET)" },
+      { value: "web", label: "Frontend Web" },
+      { value: "mobile", label: "Mobile" },
+    ],
+    required: false,
+  });
+  if (p.isCancel(platforms)) cancel(p);
+
+  const sel = { backend: false, web: null, mobile: [], arch: [] };
+  sel.backend = platforms.includes("backend");
+
+  if (platforms.includes("web")) {
+    const web = await p.select({
+      message: "Web architecture:",
+      options: [
+        { value: "spa", label: "SPA (single deployable)", hint: "default" },
+        { value: "single-spa", label: "Single-SPA", hint: "mixed frameworks / hard isolation" },
+        { value: "microfrontends", label: "Microfrontends (Module Federation)", hint: "license-gated, multi-product" },
+      ],
+      initialValue: "spa",
+    });
+    if (p.isCancel(web)) cancel(p);
+    sel.web = web;
+  }
+
+  if (platforms.includes("mobile")) {
+    const mobile = await p.multiselect({
+      message: "Mobile framework:",
+      options: [
+        { value: "flutter", label: "Flutter" },
+        { value: "react-native", label: "React Native" },
+      ],
+      required: true,
+    });
+    if (p.isCancel(mobile)) cancel(p);
+    sel.mobile = mobile;
+  }
+
+  if (sel.backend) {
+    const arch = await p.multiselect({
+      message: "Backend — distributed architecture standards (opt-in):",
+      options: ARCH_DOCS.map((a) => ({ value: a.id, label: a.label })),
+      initialValues: ARCH_DOCS.map((a) => a.id),
+      required: false,
+    });
+    if (p.isCancel(arch)) cancel(p);
+    sel.arch = arch;
+  }
+
+  return sel;
 }
 
-const existed = fs.existsSync(targetDir);
-if (existed) {
-  console.log("coding-standards/ already exists — overwriting files.\n");
+function cancel(p) {
+  p.cancel("Cancelled — nothing was written.");
+  process.exit(0);
 }
 
-fs.mkdirSync(targetDir, { recursive: true });
+// ── Help ─────────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log(`
+coding-standards — copy modern, AI-ready coding standards into your project.
 
-for (const file of files) {
-  fs.copyFileSync(path.join(standardsDir, file), path.join(targetDir, file));
+Usage:
+  npx @jeffrey2423/coding-standards              interactive
+  npx @jeffrey2423/coding-standards [flags]      non-interactive
+
+Flags:
+  --backend                 include .NET backend standards
+  --web[=track]             include web standards (track: spa | single-spa | microfrontends; default spa)
+  --mobile=flutter,react-native   include mobile standards (comma-separated)
+  --arch=a,b,... | --no-arch      backend architecture docs (default: all). ids: ${ARCH_DOCS.map((a) => a.id).join(", ")}
+  --all                     include everything
+  --yes, -y                 run non-interactively with whatever flags are given
+  --help, -h                show this help
+
+Examples:
+  npx @jeffrey2423/coding-standards --backend --web=microfrontends
+  npx @jeffrey2423/coding-standards --mobile=flutter --yes
+  npx @jeffrey2423/coding-standards --all
+`);
 }
 
-console.log(
-  `Copied ${files.length} coding standard files to coding-standards/:\n`
-);
-for (const file of files) {
-  console.log(`  - ${file}`);
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const argv = process.argv.slice(2);
+  const flags = parseFlags(argv);
+
+  if (flags.help || argv.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  let sel;
+  const nonInteractive = hasPlatformFlag(flags) || flags.yes || argv.includes("-y");
+  if (nonInteractive) {
+    sel = selectionFromFlags(flags);
+  } else {
+    sel = await interactive();
+  }
+
+  const sources = resolveSources(sel);
+  const upgrading = fs.existsSync(TARGET_DIR);
+  fs.mkdirSync(TARGET_DIR, { recursive: true });
+
+  // Idempotent: clear what we previously owned (and any v1 leftovers) first.
+  const { removed, legacy } = cleanPreviousInstall();
+  if (upgrading && (removed || legacy)) {
+    const note = legacy ? ` (incl. ${legacy} from a previous flat-layout v1 install)` : "";
+    console.log(`Existing install detected — removed ${removed + legacy} stale file(s)${note}.`);
+  }
+
+  const copied = copySources(sources);
+  generateIndex(copied, sel);
+  writeManifest(copied, sel);
+
+  console.log(`\n✓ Copied ${copied.length} standard files to coding-standards/`);
+  console.log(`✓ Generated coding-standards/INDEX.md  (selection: ${describeSelection(sel)})`);
+  console.log("\nNext: point your AI agent at coding-standards/INDEX.md (e.g. from AGENTS.md).");
 }
-console.log("\nDone!");
+
+main().catch((err) => {
+  console.error("\n✗ Installation failed:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "@jeffrey2423/coding-standards",
-  "version": "1.0.0",
-  "description": "Copy coding standards and architecture guides into your project",
+  "version": "2.0.0",
+  "description": "Pick and copy modern, AI-ready coding standards and architecture guides into your project",
   "license": "MIT",
   "bin": {
     "coding-standards": "bin/cli.js"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "bin/",
     "standards/"
   ],
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  },
   "keywords": [
     "coding-standards",
     "architecture",
     "clean-architecture",
-    "ddd"
+    "ddd",
+    "microservices",
+    "microfrontends",
+    "ai-assisted",
+    "agents"
   ]
 }

package/standards/backend/architecture/event-driven.md

@@ -0,0 +1,112 @@
+---
+title: Event-Driven Communication
+platform: backend
+track: distributed-architecture
+load_when: "Coordinating microservices — outbox, idempotency, sagas, and correlation."
+updated: 2026-06
+---
+
+# Event-Driven Communication
+
+Microservices communicate by **asynchronous events** through a broker. Synchronous HTTP is reserved for when the caller needs the answer now.
+
+> **The rule:** async when you can, sync when it hurts not to. Most microservice pain comes from abusing synchronous HTTP chains.
+
+## Why async by default
+
+| Sync HTTP chain `A→B→C→D` | Events via broker |
+|---|---|
+| Temporal coupling — D down ⇒ A fails | B/C/D can be down without affecting A |
+| Availability = product of each link | Broker absorbs spikes + retries |
+| Latency = sum of the chain | Consumers process at their own pace |
+
+**Use sync** only for "need it now" reads: validate stock before closing a sale, authenticate, check entitlement. If unsure, **start async** — converting async→sync later is easier than untangling broken chains.
+
+## Transactional Outbox (mandatory)
+
+Persisting the aggregate and publishing the event must be **atomic**. The integration event is written to an `outbox_messages` table **in the same transaction** as the aggregate change; a background worker publishes it to the broker.
+
+```sql
+BEGIN;
+  UPDATE orders SET status = 'confirmed' WHERE id = '…';
+  INSERT INTO outbox_messages (id, message_type, body, occurred_at)
+  VALUES ('…', 'OrderConfirmedV1', '{…}', now());
+COMMIT;
+```
+
+Guarantees:
+- DB fails before commit → nothing persisted, nothing published.
+- Broker fails after commit → event stays in outbox, retried.
+- **Never** any drift between persisted aggregate and published event. Eliminates the need for distributed transactions (2PC).
+
+**Implementation:** use **Wolverine** (MIT) — it provides the Outbox natively. Avoid the now-commercial MediatR/MassTransit per the [open-source-only policy](../technology-stack.md). The pattern is what matters.
+
+## Idempotency (mandatory)
+
+The outbox + broker give **at-least-once** delivery, so the same event can arrive twice. Every consumer **MUST** be idempotent.
+
+```sql
+CREATE TABLE processed_messages (
+  message_id UUID PRIMARY KEY,
+  event_type VARCHAR(100),
+  tenant_id  UUID,
+  processed_at TIMESTAMPTZ
+);
+```
+
+The consumer inserts `message_id` into `processed_messages` **in the same transaction** as the domain change; if `message_id` already exists, it skips. (Alternative for high volume: dedupe on a natural key — "`OrderClosedV1` for `order_id=X` processes once".)
+
+## Sagas / process managers
+
+A business process spanning multiple contexts is a **saga**, not an HTTP chain. The saga reacts to integration events, emits commands, persists its state, and uses **compensations** (not distributed rollback) on failure.
+
+```
+on OrderConfirmedV1   → ReserveStockCommand        (state: AWAITING_STOCK)
+on StockReservedV1    → IssueInvoiceCommand         (state: AWAITING_INVOICE)
+on InvoiceIssuedV1    → … COMPLETED
+on StockInsufficientV1→ CancelOrderCommand          (compensation)
+on InvoiceFailedV1    → ReleaseStockCommand + CancelOrderCommand
+```
+
+A compensation is a **new business fact** ("order cancelled"), not a DB undo — the events happened and consumers reacted.
+
+## Correlation ID
+
+Every message and request carries a `CorrelationId` propagated end-to-end. With **OpenTelemetry**, the `traceparent` header does this automatically, giving a distributed trace across async hops. Without it, debugging async flows is impossible.
+
+## Integration event shape
+
+```json
+{
+  "eventId": "evt_abc123",
+  "eventType": "OrderConfirmedV1",
+  "tenantId": "tenant_042",
+  "occurredAt": "2026-05-15T14:32:11Z",
+  "correlationId": "corr_xyz",
+  "data": { "orderId": "ord_001", "total": 125000, "currency": "COP" }
+}
+```
+
+Required: `eventId` (idempotency), `eventType` (versioned), `tenantId`, `occurredAt` (when it happened, not when published), `correlationId`, `data`.
+
+> Consider the **CloudEvents 1.0** envelope (`id`/`source`/`type`/`specversion`) for cross-system event formatting; it's the CNCF standard and complements broker-internal events.
+
+## Conventions
+
+- **MUST** name events in the past tense with an explicit version: `OrderConfirmedV1`. Events are facts, not commands.
+- **MUST** include `tenantId` in every event.
+- **MUST** freeze a version's contract once published; breaking change ⇒ new version; both coexist during deprecation.
+- **SHOULD** publish events for **business-significant state transitions**, not every property change. If unsure, don't publish — adding events later is easier than retiring them.
+- **SHOULD NOT** dump the internal aggregate state into an event — design the event for its consumers.
+
+## Sync calls (when necessary)
+
+When you must call synchronously, call the other service's **public API** (never its DB). Apply: retries with exponential backoff, short timeout (≤ 5s), **circuit breaker**, propagate `X-Correlation-Id`, `Idempotency-Key` on idempotent POSTs. Use **Microsoft.Extensions.Resilience (Polly v8)**.
+
+## Broker is internal
+
+The broker (RabbitMQ/Kafka) is for **internal** service-to-service traffic only. External integrators receive **webhooks**, not broker access — see [`public-api-facade.md`](public-api-facade.md).
+
+## Anti-patterns
+
+- Long sync HTTP chains; events disguised as commands (`PleaseReserveStockEvent`); events without `tenantId`; non-idempotent consumers; per-property events; events leaking internal models; missing correlation ID.

package/standards/backend/architecture/microservice-anatomy.md

@@ -0,0 +1,106 @@
+---
+title: Microservice Anatomy
+platform: backend
+track: distributed-architecture
+load_when: "Designing or implementing a microservice — its project layout, layers, and event model."
+updated: 2026-06
+---
+
+# Microservice Anatomy
+
+Every microservice follows the **same** internal structure. Structural consistency lets the team move between services without relearning conventions, and lets operations use one toolset for all. Implements [`core/clean-architecture-ddd.md`](../../core/clean-architecture-ddd.md).
+
+## The decisions
+
+- **DB-per-service (real).** Each bounded context owns its database. **No other service touches it** — access is via API or events only. A shared DB is a distributed monolith.
+- **Clean Architecture + DDD inside** each service (four layers, strict inward dependency rule).
+- **Async by default** between services; sync only when the caller needs the answer now (see [`event-driven.md`](event-driven.md)).
+- **Public, versioned contracts** at the edge (see [`public-api-facade.md`](public-api-facade.md)).
+
+## Standard solution layout (5 projects)
+
+```
+src/
+├── {Context}.Domain/             # aggregates, value objects, domain events — zero framework refs
+├── {Context}.Application/        # use cases (commands/queries), DTOs, port interfaces
+├── {Context}.Infrastructure/     # EF Core, repositories, outbox, consumers, ACL
+├── {Context}.Api/                # Minimal API endpoints
+└── {Context}.IntegrationEvents/  # published language — distributable package (NuGet)
+    ├── V1/
+    └── V2/
+```
+
+`IntegrationEvents` is the **only** project that crosses the context boundary; publish it as a versioned package so other services/adapters consume it.
+
+### Dependency rule
+
+- `Domain` → depends on nothing.
+- `Application` → Domain.
+- `Infrastructure` → Application + Domain (implements Application's interfaces).
+- `Api` → Application.
+- `IntegrationEvents` → primitives only.
+
+> Swapping the DB engine, broker, or HTTP framework must touch **only Infrastructure**. The domain never finds out.
+
+## Layer rules
+
+**Presentation (Api).** Validates request format, authenticates (JWT + tenant claim), maps HTTP → Command/Query, returns the serialized result. **No business logic, no DB access, no calls to other services.**
+- Path: `/api/v{version}/{context}/{resource}`; standard HTTP verbs/status; errors as Problem Details (RFC 9457).
+- Reads headers: `Authorization: Bearer`, `Idempotency-Key`, `X-Correlation-Id`.
+
+**Application.** CQRS use cases that **orchestrate**, never decide. A command handler: load aggregate → invoke its behavior → persist via Unit of Work → let domain events dispatch. Declares ports (`I{Aggregate}Repository`, `IUnitOfWork`, `IIntegrationEventOutbox`, `ITenantContext`). Holds the handler that **translates domain events → integration events**.
+
+**Domain.** Pure language. Aggregates guard invariants and expose behavior (`Confirm()`, not setters); emit domain events; reference other aggregates by ID. Value objects validate on construction. Every invariant has a unit test including the violation case.
+
+**Infrastructure.** Repository impls (one per aggregate root, load the whole aggregate, no `IQueryable` leaking out), ORM mappings, the **transactional outbox**, inbound **consumers** (idempotent), and the **Anticorruption Layer** that translates other contexts' models.
+
+## Mediation / messaging (2026)
+
+Per the [open-source-only policy](../technology-stack.md), use **Wolverine** (MIT) — it provides command/query mediation, the message bus, and the transactional Outbox in one package. Do **not** use the now-commercial MediatR/MassTransit. The `Mediator` source-generator or hand-rolled dispatch are also fine. The **pattern** (CQRS, domain-vs-integration events, outbox) matters, not the library.
+
+## Domain events vs integration events
+
+| Aspect | Domain Event | Integration Event |
+|---|---|---|
+| Location | Domain layer | `IntegrationEvents` package |
+| Audience | Inside the service | Other services + third parties |
+| Language | Ubiquitous, internal | Public, versioned |
+| Persistence | In memory | Outbox + broker |
+| Versioning | none | strict (`V1`, `V2`, backward-compatible) |
+| Example | `OrderConfirmedDomainEvent` | `OrderConfirmedV1` |
+
+Explicit translation between them protects the domain: the internal model can evolve freely without breaking external consumers.
+
+## Request flow
+
+```
+HTTP → JWT/tenant extracted → endpoint maps to Command → handler loads aggregate
+   → aggregate applies rules + emits domain event → persist (aggregate + outbox row, one tx)
+   → commit → domain event dispatched in-memory → translated to IntegrationEvent V1
+   → (background) outbox worker publishes to broker → other services consume idempotently
+```
+
+## Naming
+
+| Thing | Convention | Example |
+|---|---|---|
+| Bounded context | singular | `Catalog`, `Sales` |
+| Aggregate | singular | `Order`, `Product` |
+| Value object | descriptive | `Money`, `Sku` |
+| Domain event | past + `DomainEvent` | `OrderConfirmedDomainEvent` |
+| Integration event | past + version | `OrderConfirmedV1` |
+| Command | imperative + `Command` | `ConfirmOrderCommand` |
+| Query | `Get…Query` | `GetOrderByIdQuery` |
+
+## Vertical slices
+
+Clean Architecture layering and **Vertical Slice** organization combine well: keep the layer boundaries, but organize Application code by feature/use-case slice (command + handler + validator + DTO together) rather than by technical folder. This keeps related code cohesive and is the common 2026 default for new services.
+
+## Anti-patterns
+
+- Anemic CRUD-only service (no domain behavior) → it's a table with an API, not a microservice.
+- Joins across service DBs → breaks DB-per-service; the context boundaries are probably wrong.
+- Business rules in validators/endpoints → rules live in the domain.
+- Long synchronous HTTP chains `A→B→C→D` → any link down tumbles the chain; go async.
+- Shipping business code inside the `IntegrationEvents` package → it must contain only contracts.
+- Forgetting idempotency in consumers → at-least-once delivery duplicates effects.