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: Frontend-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.

Reviews and technical debt#

• ARC-043 Use automated formatting, linting, and static checks so reviewers focus on architectural and behavioral decisions.

Frontend Checks#

• ARC-081 Choose client rendering, server rendering, static generation, or hybrid strategies based on content, performance, hosting, and interaction requirements.
• ARC-082 Structure routes, layouts, components, and features with clear module ownership and predictable dependency direction.
• ARC-083 Separate view rendering from business decisions and data-access details where this improves maintainability.
• ARC-084 Keep reusable UI components focused and expose documented props, events, and accessible behaviors.
• ARC-085 Use consistent design tokens and shared UI patterns instead of duplicating styling and interactions across screens.
• ARC-086 Define where server-derived state, client state, form state, and cached data live; avoid competing sources of truth.
• ARC-087 Centralize API client logic, request cancellation, error normalization, and response mapping appropriately.
• ARC-088 Prevent leaked subscriptions, orphaned timers, repeated effects, and event listeners when components mount or unmount.
• ARC-089 Use explicit loading, empty, stale, failed, and partial-success states across data-driven views.
• ARC-090 Check route transitions, navigation history, account switching, and error boundaries for predictable state cleanup.
• ARC-091 Consider route-level or component-level code splitting when measured startup costs justify it.
• ARC-092 Assess bundle size, dependency footprint, rendering/hydration cost, and unnecessary client-side computation against project budgets.
• ARC-093 Ensure essential UI content and interactions are not blocked by avoidable long dependency chains or large startup scripts.
• ARC-094 Make semantic markup, keyboard support, and accessibility responsibilities part of component interfaces rather than one-off page patches.
• ARC-095 Keep localization, theme, formatting, and responsive concerns reusable without embedding language or device assumptions in domain logic.
• ARC-096 Confirm frontend authorization gates serve only as UX controls while backend services enforce access restrictions.

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 browser and client 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 frontend 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.