@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/audit-backend-architecture/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: audit-backend-architecture
+description: >
+  Read-only backend-architecture audit and pattern advisor, gated by stack.
+  Use when "audit backend architecture", "which pattern should I use", "am I
+  over-engineering", or "sync vs event-driven". Enforced boundaries →
+  enhance-arch-boundaries.
+license: MIT
+effort: high
+---
+
+# audit-backend-architecture — Distributed-Systems Pattern Maturity Audit
+
+**Degree of freedom: MIXED** — Fit, presence, and adopt/defer `[HIGH freedom]`;
+Phase 0 topology probes `[LOW freedom — run exactly]`. Never mark a
+pattern Missing if its tier is N/A.
+
+Read-only. Assess and recommend; do not change code. Per-call timeouts,
+retry+jitter, idempotency keys, cancellation → **`audit-resilience`**. This
+skill checks whether the *patterns* exist and whether they *fit*.
+
+Two lenses:
+
+1. **Conformance** (Phase 2) — Implemented / Partial / Missing / N/A with `file:line`.
+2. **Fit / decision** (Phase 3) — Adopt now / Adopt when [trigger] / Defer
+   (premature). *"Don't build this yet"* is a first-class finding.
+
+---
+
+## Core principle — start simple, earn every pattern
+
+Each pattern solves a *specific* problem and carries a *specific* cost. The current
+consensus is **modular-monolith-first**: >90% of systems are well served by a
+well-structured monolith; **premature decomposition is the #1 failure mode**. A
+pattern is "Missing" only if the **measurable trigger** is present — otherwise
+adopting it is over-engineering, flagged as loudly as a real gap.
+
+- **Fit beats presence.** "No service mesh / no CQRS" is a finding *only* when a trigger is present.
+- **Decide per interaction, not per system.** Sync vs event-driven is chosen per
+  boundary-crossing call (see references/patterns.md → Communication style).
+- **Distributed monolith is worse than a monolith.** Shared DB + coupled deploys
+  pays the distributed tax with none of the independence.
+- **Reversible steps.** Prefer modular monolith, façade, outbox over premature
+  service split or event-sourcing everywhere.
+
+## How to reason — Observe → Interpret → Classify → Severity
+
+1. **Observe** — topology signals + the `file:line` (or "searched, none found")
+2. **Interpret** — is there a present pain, a named future trigger, or no trigger?
+3. **Classify** — Implemented / Partial / Missing / N/A, then Adopt now / Adopt when / Defer
+4. **Severity** — dual-write, cascade-outage, silent inconsistency = Critical; Missing with no trigger = over-engineering, not a gap
+
+## Worked example
+
+> **Observe:** T1 Next.js + Supabase. `orders/service.ts` writes the row then
+> publishes to a queue in a second step. Product page hits the DB on every
+> request. No k8s, mesh, or multi-service fleet.
+> **Interpret:** a crash between write and publish loses the fulfillment event
+> (dual-write). Hot reads have no cache. Mesh and CQRS have no trigger.
+> **Classify:** Outbox = Adopt now; cache-aside = Adopt now; mesh / CQRS = Defer (T1 N/A).
+> **Severity:** Critical for dual-write; High for the uncached hot path.
+> **Finding:** Outbox (#6) | orders/service.ts | Critical | Adopt now — close
+> dual-write. Mesh | N/A (T1) | Defer — no 10+ service fleet.
+
+---
+
+## Phase 0 — Detect topology (gates every later finding)  [LOW freedom — run exactly]
+
+Architecture advice is only correct in context. Flagging "no service mesh" on a
+Next.js + Supabase app is noise; missing it on a 40-service Kubernetes fleet is
+critical. **Classify the repo first**, then apply only the patterns that fit.
+Never report a pattern as "Missing" if its topology tier is `N/A`.
+
+```bash
+# Deploy target / runtime
+rg -n --hidden -g '!node_modules' -l "vercel\.json|netlify\.toml|next\.config|supabase/config" # serverless/PaaS
+fd -H -t f 'Dockerfile|docker-compose\.ya?ml|Containerfile'                                     # containers
+fd -H -t d 'k8s|kustomize|charts|helm' ; rg -n "apiVersion:\s*(apps|networking)" -g '*.{yaml,yml}' -l # kubernetes
+# Service count / boundaries
+fd -H -t f 'package.json|go.mod|pyproject.toml|pom.xml|Cargo.toml' | rg -v node_modules         # count deployable units
+# Messaging / eventing
+rg -n "kafka|rabbitmq|amqp|nats|sqs|sns|pubsub|kinesis|redpanda|temporal|inngest|trigger\.dev" -l
+# Inter-service transport
+rg -n "grpc|@grpc|protobuf|\.proto|graphql|apollo|federation|trpc" -l
+# Mesh / gateway infra
+rg -n "istio|linkerd|consul|envoy|kong|apisig|traefik|nginx-ingress|api-?gateway|ztunnel|waypoint" -l
+```
+
+Record a **topology profile** and pick the tier:
+
+| Tier | Signals | Patterns in scope |
+|---|---|---|
+| **T1 — Serverless / modular monolith** | single deployable, Next/Supabase/edge fns, no broker | Gateway concerns (as middleware), BFF-lite, circuit breaker, idempotency/outbox-lite, hexagonal, strangler, tracing/SLO, contract tests |
+| **T2 — Containers, few services** | Dockerfiles, 2–10 services, maybe a broker | + real gateway, BFF-per-client, bulkhead, outbox+relay, saga, backpressure, ACL, mTLS |
+| **T3 — Kubernetes / microservices / event-driven** | k8s manifests, broker, gRPC/federation, 10+ services | + sidecar/service mesh (ambient), CQRS/event-sourcing, cell-based, full saga orchestration, CDC |
+
+If there are **no** backend services (static site / pure frontend), stop and report reduced
+applicability — hand any API-client concerns to `audit-fe-api`.
+
+---
+
+## Phase 1 — Research current patterns  [HIGH freedom]
+
+Follow `/research`: confirm current-year conventions and the *installed* libraries for the detected
+stack (gateway/proxy, breaker/bulkhead libs, outbox/CDC tooling, saga/workflow engines, mesh mode).
+Anchor recommendations to versions actually in the manifest — never propose a library the repo can't
+run.
+
+---
+
+## Phase 2 — Architecture maturity matrix  [HIGH freedom]
+
+For **each in-scope pattern**, mark `Implemented / Partial / Missing / N/A` with `file:line`, a
+one-line "why it matters", and the fix-delegate. **Detailed detection commands, "good vs. red-flag"
+signals, and fix targets for every pattern are in [references/patterns.md](references/patterns.md)** —
+load it and work through the applicable rows.
+
+| # | Pattern | Tier | This audit checks (structural) | Fix via |
+|---|---|---|---|---|
+| 1 | **API gateway** | T1+ | Auth, rate-limit, CORS, transform, logging, monitoring, caching enforced in **one** edge layer, not per-route copy-paste | `backend-patterns`, `audit-security` |
+| 2 | **BFF / API composition** | T1+ | Per-client shaping vs. one general API; over/under-fetch; who owns aggregation; federation at 5+ teams | `backend-patterns`, `design-api` |
+| 3 | **Circuit breaker** | T1+ | A breaker exists around downstream calls (presence/architecture only) | `audit-resilience` → `backend-patterns` |
+| 4 | **Bulkhead** | T2+ | Per-dependency resource pools; one slow dep can't exhaust shared pool | `backend-patterns` |
+| 5 | **Backpressure / load shedding** | T2+ | Queue-based load leveling, bounded queues, shed/429 under overload | `backend-patterns` |
+| 6 | **Outbox + relay/CDC** | T1+ | Dual-write closed: state + event commit atomically; relay (poll/Debezium) publishes | `backend-patterns` |
+| 7 | **Saga** | T2+ | Multi-service workflows use local txns + **compensation**; saga-pivot ordering; orchestration vs choreography | `backend-patterns` |
+| 8 | **CQRS + event sourcing** | T3 (selective) | Applied only where read/write loads diverge; immutable event log + materialized views | `backend-patterns`, `audit-db-schema` |
+| 9 | **Hexagonal / ports-and-adapters** | T1+ | Domain logic isolated from framework/IO behind ports; adapters swappable; testable without infra | `workflow-refactor`, `backend-patterns` |
+| 10 | **Anti-corruption layer** | T2+ | 3rd-party/legacy models translated at the boundary, not leaked into the domain | `backend-patterns` |
+| 11 | **Strangler-fig migration** | any (if legacy) | Incremental replacement behind a façade vs. big-bang rewrite | `workflow-refactor` |
+| 12 | **Sidecar / service mesh** | T3 | mTLS, retries, L7 policy via mesh; prefer **ambient/sidecarless** for net-new; not hand-rolled per service | `backend-patterns`, `audit-security` |
+| 13 | **Cell-based architecture** | T3 (scale) | Blast-radius isolation, shared-nothing cells, cell-scoped routing/identity | `backend-patterns` |
+| 14 | **Zero-trust / mTLS / service identity** | T2+ | Service-to-service auth, no implicit trust inside the network | `audit-security` |
+| 15 | **Distributed tracing + SLOs** | T1+ | OpenTelemetry trace/correlation IDs across hops; RED/USE metrics; SLOs/error budgets | `backend-observability` |
+| 16 | **Contract testing** | T2+ | Consumer-driven contracts (Pact/OpenAPI) between clients↔BFF and service↔service | `test-unit`, `audit-fe-api` |
+
+### Communication & data-flow choices (decide per interaction, not per system)
+
+These are *selection* decisions, not "missing features" — the answer depends on each interaction and
+the stage. Detection + trade-offs in references/patterns.md.
+
+| # | Pattern | Tier | This audit checks | Fix via |
+|---|---|---|---|---|
+| 17 | **Communication style** (sync request/response vs async event-driven) | T1+ | Each cross-boundary call fits the interaction: sync for "need the answer now / strong consistency / query"; async for "multiple reactors / independent scaling / background". Symptom to flag: one request making 5 blocking downstream calls | `backend-patterns` |
+| 18 | **Cache-aside** | T1+ | Hot read-heavy paths (product/profile/config) check cache→DB-on-miss with a TTL/invalidation story; no stale-forever or thundering-herd | `backend-patterns`, `backend-db-performance` |
+| 19 | **Database-per-service / data ownership** | T2+ (owned schemas at T1) | Each service/module owns its data; no cross-service table reads. **Anti-pattern:** shared DB + coupled deploys = distributed monolith | `backend-patterns`, `audit-db-schema` |
+
+Rules:
+- **Evidence or it didn't happen** — every verdict cites `file:line` or "searched, none found".
+- **N/A is a first-class verdict** — record *why* (topology tier), don't silently drop a row.
+- **Don't double-count** `audit-resilience`'s per-call concerns; link to it instead.
+
+---
+
+## Phase 3 — Decide: fit, not just presence  [HIGH freedom]
+
+A pattern being "Missing" is only actionable if the codebase has the **trigger** that justifies it.
+For every candidate pattern, classify it into one of three buckets from the detected symptoms:
+
+- **Adopt now** — a real, present pain maps to this pattern (evidence: `file:line` + the symptom).
+- **Adopt when [trigger]** — not yet, but name the concrete signal that should flip it on.
+- **Defer (premature)** — no trigger present; adopting now is over-engineering. Say so plainly.
+
+### Maturity ladder (climb only when the rung's trigger fires)
+
+| Stage | Shape | Add these when the trigger appears |
+|---|---|---|
+| **0. Modular monolith** | one deploy, clean module boundaries, owned schemas | this is the correct default for most systems |
+| **1. Fast & reliable monolith** | + **cache-aside** (read latency/DB load), **outbox** (dual-write), sync request/response with timeouts + a breaker | reads are hot / an event must not be lost |
+| **2. Decoupled** | + **async event-driven** for side effects, **BFF** per client, **CQRS** on the *one* read/write-divergent area | a request fans out to many blocking calls; reads & writes scale differently |
+| **3. Distributed** | + **database-per-service**, **saga** for multi-step transactions, **backpressure** | a module needs independent deploy/scale; a workflow spans services |
+| **4. Fleet** | + **service mesh** (ambient), **cell-based**, full orchestration | 10+ services, ~50+ engineers, blast-radius/residency needs |
+
+### Symptom → pattern (the decision table)
+
+| Observed symptom | Likely pattern | Not this (yet) |
+|---|---|---|
+| Repeated 100ms DB hits on hot read paths | **cache-aside** | CQRS, read replicas |
+| DB write + broker publish as two steps | **outbox (+CDC)** | 2PC, event sourcing |
+| One request makes 5 blocking downstream calls | **async event-driven** for non-critical hops | full EDA rewrite |
+| Reads and writes scale/optimize very differently | **CQRS** on that slice | event sourcing everywhere |
+| Multi-step transaction across services can half-complete | **saga + compensation** | distributed 2PC |
+| Modernizing a legacy system with risk | **strangler-fig** behind a façade | big-bang rewrite |
+| Two teams blocked on one deploy cadence | **database-per-service** split | service-per-noun |
+| Services share tables and deploy together | **fix the distributed monolith** (own schemas first) | more services |
+
+**Over-engineering guardrails (flag these as findings too):**
+- CQRS / event sourcing where reads and writes don't actually diverge → remove complexity.
+- Microservices / mesh / cell-based below the size + differential-scaling threshold → stay modular monolith.
+- Wholesale event-driven for simple two-party interactions → a single durable queue (or a sync call) is enough.
+- A split that produces a distributed monolith (shared DB, coupled deploys) → worse than the monolith.
+
+---
+
+## Phase 4 — Prioritized report + decision (read-only)  [HIGH freedom]
+
+```markdown
+## Backend Architecture Audit — [repo] — [date]
+**Topology:** [tier + evidence: N services · broker? · k8s? · transport]
+**Stage on the ladder:** [0–4]  ·  **In scope:** [patterns]  ·  **N/A (out of tier):** [list + why]
+
+### Adopt now (present pain → pattern, with evidence)
+| Pattern | Symptom (file:line) | Payoff | Fix via |
+|---|---|---|---|
+| Cache-aside | product page: 100ms DB read per request, no cache (api/products.ts:40) | ~10ms cached reads, DB load ↓ | backend-patterns |
+
+### Adopt when (named trigger, not yet)
+| Pattern | Trigger to watch for |
+|---|---|
+| Database-per-service | orders + billing need independent deploy cadence / separate teams |
+
+### Defer — would be over-engineering now
+| Pattern | Why premature |
+|---|---|
+| CQRS / event sourcing | reads and writes don't diverge; a repository is simpler |
+| Service mesh / cell-based | single modular deploy; no 10+-service fleet |
+
+### Critical (data loss / cascading outage / silent inconsistency)
+| Gap | Pattern | file:line | Why it bites in prod | Fix via |
+|---|---|---|---|---|
+| Payment writes DB then publishes to Kafka separately | Outbox (#6) | orders/service.ts:88 | Dual-write: crash between = paid order, no fulfillment event | backend-patterns |
+| No breaker/bulkhead around payment provider | #3/#4 | ... | One slow provider exhausts the pool → whole API 503s | audit-resilience/backend-patterns |
+
+### High / Medium (maturity matrix)
+| Pattern | Implemented | Partial | Missing | N/A | Fix via |
+|---|---|---|---|---|---|
+| API gateway | ... | ... | ... | | backend-patterns |
+| BFF / composition | ... | ... | ... | | design-api |
+| Hexagonal | ... | ... | ... | | workflow-refactor |
+
+### Lift-to-production roadmap (ordered)
+1. Close dual-write with Outbox (+ idempotent consumers) → backend-patterns
+2. Breaker + bulkhead on every external dependency → audit-resilience → backend-patterns
+3. Centralize gateway concerns (auth/rate-limit/CORS/logging) → backend-patterns / audit-security
+4. Distributed tracing + SLOs before scaling → backend-observability
+5. [T3] Adopt ambient mesh for mTLS/L7 instead of hand-rolled retries → backend-patterns
+```
+
+**Forbidden:** declaring "production-grade" from passing tests alone; flagging T3-only patterns
+(mesh, cell-based, CQRS) against a T1 monolith; re-auditing per-call timeouts/retries that
+`audit-resilience` owns; recommending a saga without compensation logic; recommending CQRS/event
+sourcing where read and write loads don't actually diverge; **recommending any pattern without naming
+its trigger** (fit before presence — a "Missing" with no trigger is over-engineering, not a gap);
+recommending a service split that yields a **distributed monolith** (shared DB + coupled deploys).
+
+---
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Evidenced** — `file:line` or "searched, none found", not "they probably need a mesh"
+2. **Tier respected** — T3-only rows are N/A on T1, with why
+3. **Trigger named** — every Adopt now / Adopt when / Defer cites a symptom or its absence
+4. **Right owner** — per-call timeout/retry → `audit-resilience`; mechanical layer rules → `enhance-arch-boundaries`
+5. **Nothing changed** until approved
+
+## Related
+
+- `audit-resilience` — per-call runtime resilience (timeouts, retry+backoff+jitter, idempotency keys, cancellation, PII); this audit defers those to it
+- `backend-patterns` — implement the architecture: gateway, BFF, outbox, saga, bulkhead, hexagonal (see its `references/architecture-patterns.md`)
+- `design-api` — API contract, versioning, error shapes, pagination
+- `audit-security` — auth, CORS, rate-limit-as-abuse-control, mTLS/zero-trust, injection
+- `backend-observability` — tracing, correlation IDs, RED/USE metrics, SLOs, PII redaction
+- `audit-db-schema` — the data-model side of CQRS / event sourcing / outbox tables / db-per-service
+- `backend-db-performance` — cache-aside, query optimization, read replicas for hot paths
+- `workflow-refactor` — hexagonal restructure and strangler-fig migration; modular-monolith boundaries
+- `complete-everything` — close the audited gaps to done with verification

package/skills/audit-backend-architecture/references/patterns.md

@@ -0,0 +1,386 @@
+# Backend architecture patterns — detection reference
+
+Per-pattern detection for `audit-backend-architecture`. For each in-scope pattern (per the Phase 0
+topology tier) mark **Implemented / Partial / Missing / N/A** with `file:line`. Detection commands use
+ripgrep (`rg`); adapt globs to the stack. Cross-skill fix targets are named in backticks (not links).
+
+Legend — **Applies:** lowest topology tier where the pattern is in scope (T1 serverless/monolith ·
+T2 containers/few-services · T3 k8s/microservices/event-driven).
+
+---
+
+## 1. API Gateway  · Applies: T1+
+
+**Purpose.** One edge layer owns cross-cutting concerns for all clients: authentication, rate
+limiting, CORS, request/response transformation, structured logging, monitoring, and caching. The
+failure mode is these being copy-pasted per route/function and drifting.
+
+**Detect**
+```bash
+rg -n "cors\(|Access-Control-Allow" -g '*.{ts,js,py,go}'          # CORS: central vs per-handler
+rg -n "verifyJwt|requireAuth|getSession|auth\(\)|withAuth" -g '*.{ts,js}' -c   # auth check spread
+rg -n "ratelimit|rateLimit|Ratelimit|throttle" -g '*.{ts,js,py}' -c
+rg -n "kong|apisix|traefik|envoy|nginx|api-?gateway|middleware" -l
+```
+**Good.** Auth/rate-limit/CORS/logging applied once in shared middleware or a gateway (Kong/APISIX/
+Traefik/Envoy, Next middleware, an edge layer); consistent error shape; cache headers/TTL centralized.
+**Red flags.** `Access-Control-Allow-Origin: *` per handler; auth re-implemented in each route; no
+single place to add a rate limit; logging ad hoc per function.
+**Fix via** `backend-patterns` (middleware/gateway), `audit-security` (authz/CORS correctness).
+
+---
+
+## 2. BFF / API composition / GraphQL federation  · Applies: T1+
+
+**Purpose.** A client-specific layer shapes payloads per surface (web/mobile/partner) so clients
+don't over/under-fetch. Owned by the client team; sits **behind** the gateway (gateway = policy, BFF =
+shaping). At 5+ domain teams, GraphQL federation replaces N hand-rolled BFFs.
+**Detect**
+```bash
+fd -H 'bff|for-frontend|edge-api' ; rg -n "aggregat|composition|orchestrat" -g '*.{ts,js}' -l
+rg -n "graphql|apollo|@apollo/gateway|federation|subgraph|trpc" -l
+```
+**Good.** Distinct shaping for distinct clients OR a single shared API that genuinely serves all
+clients equally; aggregation isolated from domain logic; N+1 handled (batch/DataLoader).
+**Red flags.** Mobile forced to consume a heavy web payload; auth/throttling re-done inside each BFF
+(that's gateway work); a "general-purpose API" bent painfully to every client; distributed joins in
+the client.
+**Fix via** `backend-patterns` (composition), `design-api` (contract/versioning).
+
+---
+
+## 3. Circuit breaker  · Applies: T1+  · (defers to `audit-resilience`)
+
+**Purpose.** Repeated downstream failure trips a breaker so callers fail fast instead of piling up
+threads waiting on a dead dependency (cascading failure). **This audit only confirms a breaker exists
+architecturally around each external dependency** — per-call tuning belongs to `audit-resilience`.
+**Detect**
+```bash
+rg -n "circuit.?breaker|CircuitBreaker|opossum|cockatiel|resilience4j|polly|hystrix|gobreaker" -g '*.{ts,js,py,go,java,cs}' -c
+```
+**Good.** Every synchronous outbound dependency wrapped; breaker has a fallback; half-open recovery.
+**Red flags.** Bare `fetch`/`axios` to a third party with no breaker and no timeout; retries without a
+breaker (retry storm).
+**Fix via** `audit-resilience` (full runtime review) → `backend-patterns`.
+
+---
+
+## 4. Bulkhead  · Applies: T2+
+
+**Purpose.** Isolate resource pools (threads, connections, concurrency) per dependency so one slow
+service can't exhaust system-wide capacity. The ship's-hull metaphor: one flooded compartment doesn't
+sink the vessel.
+**Detect**
+```bash
+rg -n "semaphore|bulkhead|maxConcurren|pool.?size|poolSize|Sema(phore)?\(|limit.?concurrency|p-limit" -g '*.{ts,js,py,go,java}' -c
+rg -n "max_connections|connectionLimit|pool" -g '*.{ts,js,py,go,ini,toml,yaml}' -c   # DB/HTTP pools
+```
+**Good.** Separate connection/thread pools or concurrency limits per downstream; a saturated
+dependency degrades only its own calls.
+**Red flags.** One global HTTP client / DB pool shared by fast and slow dependencies; unbounded
+concurrency to any single dependency.
+**Fix via** `backend-patterns`.
+
+---
+
+## 5. Backpressure / load shedding / queue-based load leveling  · Applies: T2+
+
+**Purpose.** Under overload, absorb bursts through a bounded queue and **shed** excess (429/503 fast)
+instead of accepting unbounded work and collapsing.
+**Detect**
+```bash
+rg -n "queue|bull|bee-queue|sqs|rabbitmq|kafka|backpressure|highWaterMark|drop|shed|429|Retry-After" -g '*.{ts,js,py,go}' -c
+```
+**Good.** Bounded queues; producer slows or requests rejected with `Retry-After` when full; async
+load leveling between spiky producers and steady consumers.
+**Red flags.** Unbounded in-memory queues/arrays growing under load; accepting all traffic then OOM;
+no 429 path.
+**Fix via** `backend-patterns`.
+
+---
+
+## 6. Outbox + relay/CDC  · Applies: T1+
+
+**Purpose.** Solve the **dual-write problem**: writing business state to the DB *and* publishing an
+event to a broker as two separate operations means one can succeed and the other fail. The outbox
+writes the event to an outbox table **in the same transaction** as the state change; a relay
+(polling, or Debezium CDC off the WAL) publishes it afterward.
+**Detect**
+```bash
+rg -n "outbox|transactional.?outbox|debezium|cdc|wal|logical.?replication" -g '*.{ts,js,py,go,sql}' -l
+# Red-flag heuristic: DB write and broker publish adjacent, not in one txn
+rg -n "publish|producer\.send|sqs.*send|kafka.*produce|emit\(" -g '*.{ts,js,py,go}' -C3
+```
+**Good.** State + event in one ACID transaction; relay publishes and marks sent; consumers idempotent
+(dedup window 24–72h) for at-least-once delivery.
+**Red flags.** `await db.save(x); await broker.publish(evt)` with no shared transaction; "we'll retry
+the publish" with no durable record; fire-and-forget events after a commit.
+**Fix via** `backend-patterns` (outbox + relay), `audit-db-schema` (outbox table/index).
+
+---
+
+## 7. Saga  · Applies: T2+
+
+**Purpose.** Multi-service business transactions without 2PC: a sequence of local transactions, each
+triggering the next, with **compensating transactions** to undo prior steps on failure. Choreography
+(events, <5 linear steps) vs orchestration (Temporal/Step Functions/Camel — branching, per-step
+timeout/retry, synchronous result). Respect the **saga pivot**: compensatable steps before the
+irreversible pivot (e.g. payment capture); retriable steps after — once past the pivot, run to
+completion, don't compensate.
+**Detect**
+```bash
+rg -n "saga|compensat|orchestrat|temporal|stepfunction|state.?machine|workflow" -g '*.{ts,js,py,go,java}' -l
+```
+**Good.** Each step commits locally + emits; compensation coded as deliberately as the happy path;
+stuck-saga timeout detection; observability (saga age, compensation rate, DLQ).
+**Red flags.** Multi-service writes with no rollback story; assuming distributed atomicity; a "saga"
+with no compensation; compensating an irreversible step.
+**Fix via** `backend-patterns` (+ pair with Outbox #6 so step events actually publish).
+
+---
+
+## 8. CQRS + event sourcing  · Applies: T3 (selective)
+
+**Purpose.** Separate the write model (commands → events) from read models (materialized views).
+Event sourcing stores state as an immutable event log (replayable, auditable). **Apply only where
+read and write loads genuinely diverge** — it is not a default.
+**Detect**
+```bash
+rg -n "cqrs|command.?handler|query.?handler|event.?store|eventsourc|projection|materializ|aggregate" -g '*.{ts,js,py,go,java,cs}' -l
+```
+**Good.** CQRS scoped to high-divergence areas; read models rebuilt from events; clear command/query
+split.
+**Red flags.** CQRS/event-sourcing applied everywhere "because microservices" (accidental
+complexity); projections with no rebuild path; event log mutated in place.
+**Fix via** `backend-patterns`, `audit-db-schema`.
+
+---
+
+## 9. Hexagonal / ports-and-adapters  · Applies: T1+
+
+**Purpose.** Domain/business logic depends on **ports** (interfaces), never directly on framework, DB,
+or HTTP. Adapters implement ports at the edges. Result: logic is testable without infrastructure and
+the framework/vendor is swappable.
+**Detect**
+```bash
+rg -n "port|adapter|domain/|application/|infrastructure/|hexagonal|ports.?and.?adapters" -l
+# Leak heuristic: framework/ORM imports inside domain/business layers
+rg -n "import .*(express|next|prisma|supabase|axios|fetch)" -g 'src/{domain,core,application}/**' 
+```
+**Good.** Domain layer imports no framework/IO; repositories/gateways behind interfaces; unit tests
+run with in-memory adapters, no DB.
+**Red flags.** Prisma/Supabase/HTTP clients imported straight into business logic; controllers with
+domain rules inline; can't test a use-case without spinning up the DB.
+**Fix via** `workflow-refactor` (restructure), `backend-patterns`.
+
+---
+
+## 10. Anti-corruption layer (ACL)  · Applies: T2+
+
+**Purpose.** Translate a third-party or legacy model into your domain's language at the boundary, so
+their schema/quirks don't leak into and corrupt your model (DDD).
+**Detect**
+```bash
+rg -n "anti.?corruption|acl|translat|mapper|adapter|dto|normaliz" -g '*.{ts,js,py,go}' -l
+```
+**Good.** External payloads mapped to internal types at one boundary; domain never references vendor
+field names/shapes.
+**Red flags.** Stripe/Salesforce/legacy JSON shapes passed raw through the domain; vendor enums used
+as domain enums.
+**Fix via** `backend-patterns`.
+
+---
+
+## 11. Strangler-fig migration  · Applies: any (only if a legacy system is being replaced)
+
+**Purpose.** Incrementally replace a legacy system behind a façade/router — route slice by slice to
+the new implementation — instead of a risky big-bang rewrite.
+**Detect**
+```bash
+rg -n "legacy|strangler|proxy|facade|feature.?flag|routing|v1|v2|deprecat" -g '*.{ts,js,py,go,yaml}' -l
+```
+**Good.** A façade routes traffic; new/old coexist; slices migrated + verified incrementally;
+decommission plan.
+**Red flags.** A months-long rewrite branch with no incremental cutover; old and new diverging with
+no router.
+**Fix via** `workflow-refactor` (+ `workflow-feature-flag` for gated cutover).
+
+---
+
+## 12. Sidecar / service mesh  · Applies: T3
+
+**Purpose.** Offload mTLS, retries, timeouts, L7 routing/traffic-splitting, and telemetry to a mesh
+instead of hand-rolling them in every service. Prefer **ambient / sidecarless** (e.g. Istio
+ambient: node-level ztunnel for mTLS + optional per-namespace waypoint proxies for L7) over per-pod
+sidecars for net-new clusters.
+**Detect**
+```bash
+rg -n "istio|linkerd|consul-connect|envoy|ztunnel|waypoint|sidecar|VirtualService|DestinationRule|PeerAuthentication" -g '*.{yaml,yml}' -l
+```
+**Good.** mTLS + identity-based authz from the mesh; retries/circuit-breaking/traffic-splitting via
+mesh policy; consistent observability; ambient mode for new clusters.
+**Red flags.** Every service hand-rolling mTLS/retries/telemetry; classic per-pod sidecars adopted
+for a net-new cluster without reason; no service identity.
+**Fix via** `backend-patterns`, `audit-security` (mTLS/zero-trust).
+
+---
+
+## 13. Cell-based architecture  · Applies: T3 (scale / residency)
+
+**Purpose.** Partition the system into shared-nothing **cells** (own compute + data + config) mapped
+to regions/tenant tiers, so a failure or noisy neighbor is contained to one cell's blast radius.
+Regional/tenant routing directs users to their cell.
+**Detect**
+```bash
+rg -n "cell|shard|tenant|region|partition|blast.?radius|shuffle.?shard" -g '*.{ts,js,py,go,yaml,tf}' -l
+```
+**Good.** Cells share nothing at runtime; same artifact deployed to all cells; cell-scoped
+identity/routing; centralized observability with cell labels.
+**Red flags.** One global cluster/DB as a single failure domain at scale; cross-cell runtime coupling;
+no per-cell routing.
+**Fix via** `backend-patterns` (usually an infra/platform initiative — flag, don't force).
+
+---
+
+## 14. Zero-trust / mTLS / service identity  · Applies: T2+
+
+**Purpose.** No implicit trust inside the network: services authenticate each other (mTLS + workload
+identity), not "it's on the VPC so it's fine".
+**Detect**
+```bash
+rg -n "mtls|mutual.?tls|spiffe|spire|PeerAuthentication|serviceaccount|workload.?identity|client.?cert" -l
+```
+**Good.** Service-to-service calls authenticated; secrets scoped per workload; internal endpoints not
+implicitly trusted.
+**Red flags.** Internal APIs with no auth ("private network"); shared god-tokens between services;
+plaintext internal traffic.
+**Fix via** `audit-security` (+ mesh #12 for enforcement).
+
+---
+
+## 15. Distributed tracing + SLOs  · Applies: T1+
+
+**Purpose.** A request is traceable across hops (OpenTelemetry trace/correlation IDs); RED
+(Rate/Errors/Duration) and USE (Utilization/Saturation/Errors) metrics exist; SLOs and error budgets
+define "healthy".
+**Detect**
+```bash
+rg -n "opentelemetry|@opentelemetry|otel|traceparent|trace.?id|correlation.?id|x-request-id|span|SLO|error.?budget" -g '*.{ts,js,py,go}' -l
+```
+**Good.** Trace/correlation ID propagated end-to-end; spans around external calls; dashboards +
+alerts; SLOs defined before scaling.
+**Red flags.** Logs with no correlation ID; can't follow a request across services; alerting on
+symptoms only; no SLO.
+**Fix via** `backend-observability`.
+
+---
+
+## 16. Contract testing  · Applies: T2+
+
+**Purpose.** Consumer-driven contracts (Pact) or schema contracts (OpenAPI/GraphQL) verify that
+clients↔BFF and service↔service agree, so an upstream change can't silently break a downstream.
+**Detect**
+```bash
+rg -n "pact|contract.?test|openapi|swagger|schemathesis|dredd|json.?schema|consumer.?driven" -l
+```
+**Good.** Contracts versioned + verified in CI; provider verification gates deploys; breaking changes
+caught before release.
+**Red flags.** Integration relies on manual testing; "it worked in staging"; no schema/contract
+between producer and consumer.
+**Fix via** `test-unit` (write/verify), `audit-fe-api` (FE↔BE contract drift).
+
+---
+
+## 17. Communication style — sync request/response vs async event-driven  · Applies: T1+
+
+**Purpose.** Choose the model **per interaction that crosses a boundary**, not for the whole system.
+Sync (REST/gRPC) trades loose coupling for immediate certainty; async (queue/pub-sub) trades certainty
+for decoupling and independent scaling. Mature systems are hybrid: sync at the edge, async for side
+effects, bridged by the outbox (#6).
+**Decide** — signals that point each way:
+
+| Signal | Leans |
+|---|---|
+| Caller needs an immediate success/failure answer | **sync** request/response |
+| Strong consistency is a hard business requirement | **sync** |
+| The interaction is a simple, well-known two-party contract; it's a query | **sync** (REST for edge/cacheable, gRPC for internal high-throughput) |
+| Multiple unrelated services must react to the same fact | **async** event-driven (pub/sub) |
+| Producer and consumer scale / fail independently; work is background | **async** (queue for one consumer, event stream for many) |
+| New consumers should be addable without changing the producer | **async** |
+
+**Detect**
+```bash
+rg -n "fetch\(|axios|got\(|httpx|HttpClient|grpc|\.rpc\(" -g '*.{ts,js,py,go}' -c        # sync calls
+rg -n "publish|emit\(|producer\.send|queue|kafka|rabbitmq|sqs|sns|nats|pubsub|EventBridge" -c  # async
+# Anti-pattern heuristic: many blocking downstream calls inside one handler
+rg -n "await .*(fetch|axios|rpc|client\.)" -g '*.{ts,js}' -C1
+```
+**Good.** Each cross-boundary call matches the interaction; a durable queue/DLQ for async; sync calls
+have timeouts + a breaker (see `audit-resilience`).
+**Red flags.** One request making 5+ blocking downstream calls (should be async/parallel); wholesale
+EDA for a simple two-party call (needless complexity); async with no dead-letter queue (silent loss);
+"everything sync" (cascading failure) or "everything async" (eventual consistency + debugging pain
+everywhere).
+**Fix via** `backend-patterns` (see references/architecture-patterns.md → sync-vs-async).
+
+---
+
+## 18. Cache-aside (lazy loading)  · Applies: T1+
+
+**Purpose.** For hot, read-heavy, tolerably-stale data (product details, user profile, config), check
+the cache first; on a miss, read the DB and populate the cache. Turns ~100ms DB reads into ~10ms cache
+reads and sheds DB load. The correctness lives in **invalidation**, not the read.
+**Detect**
+```bash
+rg -n "redis|memcached|upstash|unstable_cache|revalidate|cache\.(get|set)|lru|node-cache" -g '*.{ts,js,py,go}' -l
+# Red-flag heuristic: hot read straight to the DB with no cache
+rg -n "findUnique|findFirst|SELECT .* WHERE id" -g '*.{ts,js,py,sql}' -C2
+```
+**Good.** Read-through on hot paths with an explicit TTL; a clear invalidation path on write
+(delete/update the key, or tag-based revalidate); protection against stampede/thundering-herd on
+popular keys (single-flight / jittered TTL).
+**Red flags.** Every read hitting the DB on a hot path; caches with no TTL and no invalidation (stale
+forever); caching user-specific/private data under a shared key; cache write *before* the DB commit.
+**Fix via** `backend-patterns`, `backend-db-performance`.
+
+---
+
+## 19. Database-per-service / data ownership  · Applies: T2+ (owned schemas already matter at T1)
+
+**Purpose.** Each service (or, in a modular monolith, each module) **owns its data**; others reach it
+only through its API/events, never by reading its tables. This is what makes independent deployment
+and scaling real. At T1 the same discipline applies logically (separate schemas / clear ownership)
+even on one physical database.
+**Detect**
+```bash
+rg -n "JOIN .*\." -g '*.{sql,ts,js,py}' -l                 # cross-domain joins (ownership leak?)
+rg -n "schema|search_path|DATABASE_URL|datasource" -g '*.{ts,js,py,prisma,toml,env}' -l
+```
+**Good.** One writer per table/aggregate; cross-service data via API/events (or an outbox); modular
+monolith with separated schemas and interface-only access between modules.
+**Red flags — the distributed monolith:** multiple services reading/writing the same tables; services
+that *must* deploy together; shared ORM models across service boundaries. This is **worse** than a
+monolith — the distributed tax with none of the independence. Fix ownership *before* splitting further.
+**Fix via** `backend-patterns`, `audit-db-schema`.
+
+---
+
+## Decision framework — fit before presence (used in Phase 3)
+
+A pattern is only "Missing" (actionable) when the codebase shows the **trigger** that justifies its
+cost. Otherwise adopting it is over-engineering — flag *that* instead.
+
+**Maturity ladder** (climb a rung only when its trigger fires):
+
+| Stage | Default shape | Trigger to add the next patterns |
+|---|---|---|
+| 0 | Modular monolith, owned schemas, sync + timeouts | *(correct default for >90% of systems)* |
+| 1 | + cache-aside, + outbox | hot read paths hit the DB repeatedly; an event must not be lost on crash |
+| 2 | + async event-driven side effects, + BFF, + CQRS (one slice) | a request fans out to many blocking calls; reads & writes scale/optimize differently |
+| 3 | + database-per-service, + saga, + backpressure | a module needs independent deploy/scale; a workflow spans services and can half-complete |
+| 4 | + service mesh (ambient), + cell-based, + orchestration | 10+ services, ~50+ engineers, blast-radius / data-residency needs |
+
+**Anti-over-engineering (each is a finding):** CQRS/event-sourcing without read/write divergence;
+microservices/mesh/cell-based below the size + differential-scaling threshold; wholesale EDA for
+two-party interactions; any split that yields a distributed monolith. When in doubt, **stay on the
+lower rung** — reversible, cheaper, and almost always sufficient.