audit-backend-architecture

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

# 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.

## This skill vs neighbors

| Skill | Owns |
|---|---|
| **audit-backend-architecture** (this) | Read-only architecture audit and pattern advisor, gated by stack |
| `enhance-arch-boundaries` | Enforce architecture boundaries in CI: layer direction, forbidden imports |
| `backend-patterns` | Apply backend patterns: queues, caching, rate limits, serverless/edge |

---

## 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|apisix|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` |

From kensaurus/skills, MIT.

More from kensaurus/skills