/codebase-architecture

Brief Conventions and Rollout

The entry format for the brief's conventions, testing, and quality-bar sections, the convention shapes that recur, and the rollout and rollback section. Load when writing any of those sections of an architecture brief. Make conventions enforceable; leave generic style advice out.

Contents

• Entry format
• Convention shapes
• Testing shapes
• Rollout and rollback

Entry format

Each convention needs four fields:

• Boundary: the files, modules, package, or entrypoint the rule applies to.
• Failure mode: the bug, drift, or operational failure the rule prevents.
• Enforcement: the lint rule, type check, test, generator, or review gate that catches violations.
• Owner: the package, team, or module that owns exceptions.

A convention that cannot name all four is a preference, and preferences do not go in the brief.

Convention shapes

• Quality bar: the product qualities the architecture protects, usually reliability, speed, clarity, efficacy, and efficiency. Enforcement: release checklist plus targeted tests, monitoring, and rollback gates.
• Surface-area budget: every new module, route, job, entrypoint, feature flag, setting, and deployable surface adds relationship cost. Enforcement: the brief names the new relationships, ownership, tests, observability, and deletion or sunset path before the surface is accepted.
• Complete vertical slices: a slice ships with its contracts, error paths, user-facing states, observability, and rollback path. Enforcement: PR template or release gate rejects happy-path-only slices.
• Entropy control: old flows, duplicate paths, and low-value features are deleted, sunset, or marked legacy with an owner and review date. Enforcement: legacy registry, deprecation grep, or scheduled cleanup check.
• Domain language: one canonical name per business concept; aliases listed only for migration. Enforcement: domain glossary plus tests or lint for generated API and schema names.
• Layer imports: handlers import services; services import DAOs and clients; DAOs import neither handlers nor request objects. Enforcement: import-boundary lint.
• Context initialization: every RPC, HTTP, job, worker, and CLI entrypoint initializes RequestContext before shared services run. Enforcement: entrypoint tests or a fail-closed bootstrap helper.
• Auth policy registration: each route or RPC method declares an auth policy at registration. Enforcement: type-level registry or startup validation.
• Monorepo dependency ownership: each deployable app declares its runtime dependencies; root manifests hold workspace tooling only. Enforcement: package-manager constraints or dependency lint.
• Dependency-version single source: one place defines each shared dependency's version across the monorepo; apps reference it rather than pinning their own. On pnpm that is catalog:; on npm workspaces (which have no catalogs) it is syncpack version groups. Enforcement: syncpack lint or the package manager's own check in CI.
• Tool-owned ordering: append-only ordered artifacts (DB migrations, changelog entries) are generated by the CLI, never hand-authored; a hand-typed future-dated migration blocks every one after it. Enforcement: CI check that new entries are tool-generated and monotonic.

Testing shapes

• Test data isolation: integration and E2E tests generate unique tenant, user, and resource IDs per run. Enforcement: fixture helper plus a test for hard-coded shared IDs.
• Invariant testing: core invariants hold for any generated input and are asserted after every step of a generated operation sequence, not only at the end. Enforcement: property-based tests plus a harness that injects between-step assertions.
• Idempotency testing: every operation that touches the outside world produces no second effect when replayed. Enforcement: a test middleware that repeats each declared operation and asserts no change from the second call.
• Crash and resume testing: long multi-step flows survive dying between any two steps. Enforcement: tests that inject a failure at each step and assert the flow resumes to a consistent state.
• Round-trip testing: serialize/deserialize and convert/convert-back land where they started, or within a known tolerance. Enforcement: generative round-trip tests over the boundary types.
• Backward compatibility: current code still reads records written by old code. Enforcement: a corpus of real old-format payloads asserted to deserialize and project correctly.

Rollout and rollback

Prefer instant rollback over perfect pre-merge hygiene: treat PRs as broadcast rather than permission, and buy safety with the reversal path instead of the gate.

• Pin every deploy to a commit SHA (build arg or tag) so "what is running" is always answerable.
• Ship a one-click rollback workflow: inputs are the target SHA, the environment, and a mandatory free-text reason; it validates the SHA exists before deploying and emits a summary of what moved.
• End the workflow with a post-rollback checklist: watch error rates filtered by the deployed version, then investigate the root cause. A rollback without a follow-up reschedules the incident.

Enforcement: the workflow itself. A deploy path that cannot name its running SHA, or a rollback that runs without a recorded reason, fails the Operability check in the validation loop.