architecture-review-checklist

Architecture Review Checklist

Purpose

Provides a structured methodology for evaluating compiled architecture documents produced by the architecture generation pipeline. The reviewer uses this checklist to systematically verify cross-domain consistency, requirements completeness, IL standards compliance, open question quality, and diagram accuracy.

When to Use

Invoke this skill before reviewing any architecture document. Follow each section sequentially — do not skip sections even if they seem unlikely to surface issues.

Checklist

1. Cross-Domain Consistency

Verify alignment between every pair of domains present in the document. For each check, read the relevant sections and compare specific details (names, types, fields, relationships).

API ↔ Data Model

• Every API endpoint that reads data has a corresponding DynamoDB access pattern (query or get)
• Every API endpoint that writes data has a corresponding write operation in the data model
• Entity names in API request/response models match entity names in the data model
• Field names and types in API contracts are consistent with DynamoDB attribute definitions
• Pagination approach in APIs (cursor-based vs offset) is supported by the DynamoDB access patterns

API ↔ Events

• Event schemas reference the same entity names and field names as API contracts
• Services identified as event producers are the same services that own the relevant API endpoints
• Async operations (202 Accepted) have corresponding event flows for status updates
• Event payloads contain sufficient data for consumers (no implicit dependencies on API calls)

Data Model ↔ Events

• Entities that need event-driven sync have DynamoDB Streams enabled
• Event payloads are derivable from the data model attributes (no fields that don't exist in the model)
• CQRS patterns (DynamoDB → OpenSearch) are reflected in both the data model and event flow sections
• Event versioning strategy is consistent with data model evolution strategy

Frontend ↔ API

• Frontend components reference API endpoints that exist in the backend architecture
• Data shapes consumed by the frontend match API response schemas
• Authentication flows in the frontend align with the backend auth approach
• Error handling in the frontend accounts for the error response format (RFC 7807) defined by the backend

Testing ↔ All Domains

• Pact contract boundaries map to actual service-to-service interfaces defined in the architecture
• E2E test plan covers critical user flows implied by the frontend component hierarchy and routing plan
• Accessibility test targets match the pages/components defined in the frontend architecture
• Unit testing standards match the language/framework choices in the backend architecture

Overview Diagram ↔ Domain Sections

• Every component in the Architecture Overview diagram appears in a domain section
• Every component in domain sections appears in the Architecture Overview diagram
• Connections between components in the overview diagram match the interactions described in text

2. Requirements Completeness

For each requirement or user story from the source Confluence page:

• At least one domain section addresses the requirement
• The architecture provides enough detail to implement the requirement (not just a mention)
• Acceptance criteria are achievable with the proposed architecture
• No architecture components exist that don't trace back to a requirement (scope creep check)

Classification:

• COVERED: The requirement is fully addressed by the architecture — implementation could proceed based on this design
• PARTIAL: The requirement is mentioned but missing key details (e.g., the API is defined but the data model doesn't include a needed entity)
• MISSING: The requirement is not addressed anywhere in the architecture

3. IL Standards Compliance

Check each standard. Only flag violations — do not flag things that are correct.

Technology Stack

• New backend services use Kotlin/Micronaut (not Node.js/Express/NestJS for services)
• TypeScript/Node.js is only used for Lambda functions
• Cache references use "Valkey" (not "Redis")
• DynamoDB tables use on-demand capacity (not provisioned)
• DynamoDB tables follow one-table-per-service pattern
• All partition keys (table and GSI) have high cardinality
• DynamoDB → OpenSearch sync uses OSI pipeline (not Lambda, unless justified)
• Frontend E2E tests use Playwright (not Cypress for new work)
• Accessibility targets WCAG 2.1 AA with axe-core
• Contract tests use Pact.io

Architecture Patterns

• No third-party API gateways (Kong, AWS API Gateway) recommended
• Auth handled in application code (not gateway)
• JWT validation checks all four claims (signature, aud, iss, exp)
• Refresh tokens stored in HTTPONLY cookies (not localStorage)
• DLQ management uses Argus (no custom DLQs)
• Deployment uses OTK v2 (il.yaml, deploy.yaml, Dockerfile)
• Observability includes New Relic APM and structured JSON logging with correlationId

Naming Conventions

• DynamoDB key naming: pk, sk, gsi1pk, gsi1sk
• Entity type prefixes: ENTITY_TYPE# (uppercase with underscores)
• API paths: /api/v1/{resource} (plural nouns, kebab-case)
• Error format: RFC 7807 Problem Details

4. Open Question Quality

• Each open question describes a genuine ambiguity that requires human decision-making
• No open questions have answers that are deterministic from IL standards (these should be resolved, not deferred)
• Requirements ambiguities that could affect implementation are flagged as open questions
• Open questions include enough context for decision-makers to understand the trade-offs

5. Diagram Accuracy

For each Mermaid diagram in the document:

• The diagram syntax is valid (would render correctly)
• Components in the diagram match those described in the surrounding text
• All relationships/connections are shown (no missing arrows)
• The diagram does not include components that aren't discussed in the text
• Labels are clear and match the naming used in the text

Severity Definitions

Severity	Definition	Impact
CRITICAL	Blocks implementation — cross-domain inconsistency that would cause incorrect behavior, missing requirement that's core to the feature, or standards violation that would fail security/compliance review	Must be resolved before implementation planning
MAJOR	Will cause issues — inconsistency that would require rework during implementation, partial requirement coverage that needs design clarification, or standards violation with operational impact	Should be resolved before implementation
MINOR	Cosmetic or low-risk — diagram inaccuracy, naming inconsistency, or standards deviation with minimal impact	Can be addressed during implementation

Calibration

Your default assumption should be that the architecture has consistency gaps. Multi-agent compilation inherently risks cross-domain misalignment.

• A verdict of APPROVE should mean you are confident a developer could implement from this document without encountering contradictions between sections.
• If you find zero CRITICAL or MAJOR findings, explicitly document what you checked across each domain pair and why you are confident.
• The most common issues are: API endpoints that reference entities not fully defined in the data model, event schemas with fields that don't exist in the data model, and test boundaries that don't match actual service interfaces.