/sota-architecture

name: sota-architecture
description: >-
  State-of-the-art software and system architecture rules (2026) for both
  building and auditing. Use when designing, building, refactoring, or
  extending system architecture — boundaries, DDD, hexagonal/clean
  architecture, event-driven design, CQRS, sagas, messaging, caching,
  sharding, multi-tenancy, resilience, scalability, 12-factor/cloud-native —
  AND when auditing existing architecture for quality (design review,
  anti-patterns like distributed monolith or shared database,
  reliability/scalability assessment). Trigger keywords: architecture, system
  design, microservices, monolith, serverless, bounded context, DDD,
  aggregate, hexagonal, clean architecture, event-driven, Kafka, NATS,
  JetStream, messaging, pub/sub, stream, consumer, queue, saga, outbox,
  idempotency, CQRS, resilience, circuit breaker, retry, timeout,
  backpressure, caching, sharding, partitioning, multi-tenant, 12-factor,
  cloud-native, feature flag, ADR, scalability, anti-pattern, design review,
  architecture audit.

SOTA Architecture (2026)

Purpose

Dense, enforceable rules for software and system architecture: choosing styles, drawing boundaries, surviving distributed systems, scaling state, and shipping cloud-natively. One rule set, two modes — apply the rules while **building**, or check code against them while **auditing**. All substance lives in `rules/`; this file routes you to the right one.

BUILD mode — designing or writing code

1. **Identify the decision surface.** Before writing code, list the architectural decisions in play (style, boundaries, sync/async, datastore, tenancy, caching). Use the index below to read the relevant rules files *before* committing to a design — minimum: 01 for any new system/service, 03 for anything crossing a network, 07 always (know what failure looks like). 2. **Default to boring.** Modular monolith, one database, sync calls within the deadline budget, queues only where semantics are async. Escalate complexity only when a rule's stated forces apply, and record it. 3. **Write the ADR first** for any Type 1 (hard to reverse) decision: context, decision, consequences (must include downsides), rejected alternatives. Put it in `docs/adr/`. 4. **Apply rules as you code, not after.** Timeouts/retries/idempotency at every integration point as you create it; ports before adapters; tenant_id and trace context plumbed from the first commit. Retrofitting these is 10x the cost. 5. **Encode the rules you adopted as fitness functions** (import-rule tests, contract tests in CI, SLO alerts) so they survive you. 6. **Before finishing**, run the relevant "Audit checklist" sections from each rules file you used against your own output. Fix what fails or document why it's accepted (in the ADR).

AUDIT mode — reviewing existing code or designs

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

1. **Scope first.** Identify what you're auditing (whole system, one service, one PR) and read the matching rules files from the index. For a full architecture audit, work through every rules file; for a PR, pick by topic. 2. **Drive from the checklists.** Every rules file ends with an "Audit checklist" of yes/no questions — answer each with evidence (file:line, config, trace), never from the README's claims. Use [rules/07](rules/07-anti-patterns-catalog.md) detection signals as concrete grep/inspection targets. 3. **Verify mechanically where possible:** grep for client construction without timeouts, imports crossing layers, queries missing tenant scoping, `latest` image tags, dual-writes (DB write + publish in the same function without an outbox), shared DB credentials. 4. **Report every violation as a finding** in this exact format:

   [SEVERITY] file:line — Rule violated: <rules-file §section, short rule name>
   Evidence: <what you observed>
   Impact: <what fails and when>
   Fix: <specific, smallest correct remediation>
   Effort: trivial | small | medium | large

5. **Severity conventions:**

• **Critical** — data loss/corruption, cross-tenant leak, full-outage mechanism, money/security path failing open: missing idempotency on payments, business data only in cache, shared-DB writes, liveness probe checking the DB, secrets in git, no owning team.
• **High** — outage-magnifier or rollback-blocker: missing timeouts on hot paths, retry multiplication, lockstep deploys, breaking schema changes, sync chains > 2 on revenue paths, DLQ without alerting, missing read-your-writes on user-visible saves.
• **Medium** — erodes evolvability/operability: leaky abstractions, anemic core domain, stale feature flags, missing ADRs, event spaghetti without cycles, unscoped shared libs.
• **Low** — hygiene: naming drifting from ubiquitous language, missing runbook sections, unjittered crons that haven't yet caused incidents.
• When in doubt between two severities on a revenue-, security-, or data-touching path, pick the higher.

6. **Summarize** findings by severity with counts, then list the top 3 structural themes (not symptoms) and the order to fix them (Critical correctness → rollback/deploy safety → evolvability).

Rules index

| File | Topics | Read this when... | |---|---|---| | [`rules/01-architecture-styles-and-decisions.md`](rules/01-architecture-styles-and-decisions.md) | Modular monolith vs microservices vs serverless, **monorepos (build-enforced visibility, CODEOWNERS enforcement, workspace lockfiles, affected-only CI and its global inputs, §2a)**, extraction forces, ADRs, evolutionary architecture, fitness functions, Type 1/2 decisions, retiring a service completely, Conway's law, strangler fig, buy vs build | Starting a system, proposing/justifyi