03 — Architecture and Code Quality Checklist#

Review design trade-offs, system boundaries, maintainable code, engineering reviews, decision records, and API/frontend architecture. This checklist evaluates structure and evolvability; it complements the dedicated Testing, Security, DevOps, and Performance files.

Scope: Backend / API-specific. This file is one part of the 03_Architecture_and_CodeQuality.md checklist. Apply the domain-wide release gate across all applicable scope files; each checklist ID remains unique.

Review details#

• Project / product:
• Release / version / environment:
• Scope and applicable jurisdictions / markets:
• Reviewer / owner:
• Review date:
• Decision: Pending / Approved / Approved with documented exceptions / Blocked

How to use#

1. Copy this reusable checklist into a project-specific review; leave all boxes unchecked in this shared repository.
2. Mark [x] only after confirming an item through source review, current diagrams, ADRs, build rules, interface contracts, or other evidence. Record failed checks and documented N/A decisions separately in project review notes or issues using their ARC IDs.
3. Prioritize consequential design choices and maintainability risks. A modular monolith, services, or another pattern may all be appropriate depending on the project; no specific architecture is universally required.
4. Check ## API Checks and ## Frontend Checks independently where applicable. Refer detailed functional testing, security vulnerabilities, accessibility conformance, and performance validation to their corresponding checklists.
5. Reassess when major dependencies, product boundaries, public contracts, staffing, or architectural assumptions change.

Architecture and system boundaries#

• ARC-001 Document the system context, users, external systems, deployment environment, and critical data flows in diagrams or equivalent artifacts.
• ARC-012 Check that cross-cutting concerns (identity, configuration, telemetry, caching) have consistent ownership without centralizing business rules in gateways.
• ARC-015 Record deployment units, stateful/stateless components, environment boundaries, and independent release requirements.

Code organization and maintainability#

• ARC-031 Keep database access, transactions, and schema evolution responsibilities explicit in the code structure.

Architecture decisions and evolution#

• ARC-060 Specify transition strategies for changes to storage, queues, runtime, frameworks, or public contracts.

API Checks#

• ARC-065 Make each API's ownership and business capability explicit; avoid endpoints that bypass intended domain boundaries.
• ARC-066 Separate transport concerns from domain rules so the same invariants hold across different consumers.
• ARC-067 Maintain a versioned, machine-readable API contract (such as OpenAPI for HTTP APIs) when appropriate.
• ARC-068 Check that request/response models do not leak internal database schemas or framework-specific implementation details unnecessarily.
• ARC-069 Document resource identity, ownership, operations, data representation, and error contracts consistently.
• ARC-070 Design pagination, filtering, sorting, and partial updates with predictable, documented semantics when supported.
• ARC-071 Define backward-compatibility expectations for fields, enums, nullability, status codes, and request behavior.
• ARC-072 Make deprecations and migrations visible to consumers before removing widely used contracts.
• ARC-073 Specify whether clients may retry writes and how idempotency is implemented where needed.
• ARC-074 Document synchronous versus asynchronous operations, completion signals, polling, and event delivery when relevant.
• ARC-075 Define timeouts, failure boundaries, throttling/quotas, and fallback behaviors between dependent services.
• ARC-076 Check that shared API clients/SDKs encapsulate protocol details instead of spreading low-level calls across unrelated modules.
• ARC-077 Ensure API gateway layers route, authenticate, and observe traffic without becoming the sole owner of domain logic.
• ARC-078 Validate consumer/provider contract tests or compatibility checks are part of the change workflow.
• ARC-079 Document API change owners, integration dependencies, and how breaking changes trigger release coordination.
• ARC-080 Verify cross-tenant authorization and data access remain enforced in the responsible service rather than relying on frontend checks alone.

Release gate#

• Critical component boundaries, data ownership, public interfaces, and major failure/dependency paths are understood and reviewed by accountable engineers.
• Material architectural decisions are recorded, including alternatives, trade-offs, owners, and any unresolved risks.
• Changes affecting critical APIs or frontend architecture have documented compatibility and migration implications, with an approved path for affected consumers.
• The proposed code and structure have received the required engineering review, and no unresolved high-impact maintainability or design defect remains without documented acceptance by an authorized owner.
• All open architecture/code-quality blockers have named owners, dispositions, and follow-up dates in project-specific records.

Domain-specific approval rule: Block architecture approval for unowned critical interfaces or data, undocumented breaking changes, structural defects likely to invalidate core system guarantees, or unaccepted high-impact maintainability risks. Passing this review does not establish that functional, security, or operational testing has succeeded.

Trusted references and scope#

These checks interpret selected guidance into practical review questions; they are not direct quotations or a certification against any one framework.

• Microsoft Azure Architecture Center — Architecture styles — choosing styles with explicit trade-offs and domain fit.
• Microsoft Azure Architecture Center — Design for evolution — high cohesion, loose coupling, contracts, domain ownership, and controlled change.
• AWS Well-Architected Framework — Operational excellence design principles — small reversible changes, failure anticipation, and iterative operational improvement.
• AWS Prescriptive Guidance — Architectural decision records — documenting and communicating important architectural decisions.
• AWS Prescriptive Guidance — ADR best practices — ownership, status, review cadence, and preserved decision history.
• Google Engineering Practices — What to look for in a code review — readability, complexity, design, correctness, and code health.
• Google Engineering Practices — Small changes — focused, reviewable, reversible changes.
• OpenAPI Specification 3.2.1 — machine-readable HTTP API contracts when applicable.
• web.dev — Rendering on the web — selecting frontend rendering approaches according to their trade-offs.
• web.dev — Code-split JavaScript — modular JavaScript loading and startup responsiveness.

Applicability: Adapt check granularity to the project's size, language, architecture style, team, and risk. Independent deployment, event messaging, OpenAPI, and browser rendering are conditional—not mandatory for every project. Prefer simple designs that satisfy measured requirements.

Source review date: 2026-11-12.

Suggested testing tools#

Choose tools appropriate to the project's stack and risks; automation supports evidence but does not approve the checklist.

• Test focus: dependency boundaries, code quality, interface contracts, and architectural regression; include API and service behavior where applicable.
• Cross-stack: Semgrep + dependency-cruiser.
• Python: Ruff + mypy + pytest; for pytest-based suites, run python -m pytest -q.
• TypeScript: TypeScript tsc + ESLint + Vitest; for Vitest-based suites, run npx vitest run (or npx playwright test for E2E).
• JavaScript: ESLint + Jest; for Jest-based suites, run npx jest --ci (or npx playwright test for E2E).
• Evidence: Save tool versions, configuration, test environment, fixtures, results, and links in project-specific review records using the existing checklist IDs. Expert review remains necessary where relevant.

Suggested AI skills for verification#

These are optional agent review aids, not automated passes or release approval. Each linked repository had at least 1,000 GitHub stars when checked on 2026-11-12; counts are per repository, not per skill, and do not indicate security or correctness.

• improve-codebase-architecture — Review modules, boundaries, and coupling (mattpocock/skills, 322,608 repo stars).
• code-review-and-quality — Inspect maintainability and correctness risks (addyosmani/agent-skills, 116,378 repo stars).
• architecture-patterns — Check architecture and integration decisions (wshobson/agents, 42,437 repo stars).

How to check: In a project-specific copy, have the agent audit the backend / API scope and map findings to this file's existing checklist IDs, with code/configuration references, reproducible test results, failed or inapplicable cases, and uncertainties. Independently verify findings; keep shared template boxes unchecked and retain human approval requirements.

Before use: Read the skill's SKILL.md, referenced scripts, license, and requested tool permissions. Only execute vetted skills with appropriate access in a controlled environment.

Important warning: reference only#

⚠️ Reference only — not a definitive or exhaustive checklist. This template is a starting point for review, not the ultimate authority or a guarantee of project safety, quality, regulatory compliance, accessibility, security, or launch readiness.

Use project-specific judgment and independent verification. Requirements and risks evolve and differ by project, technology, and jurisdiction. Adapt the checks, consult current authoritative sources, perform relevant tests, and obtain qualified specialist review or approval when appropriate. Checking every box does not replace these steps.