| name | architecture-review |
| description | Enterprise architecture review with comprehensive codebase analysis and prioritized remediation plan. Activate when reviewing architecture, performing codebase audit, assessing architecture quality, evaluating system design, or scoring production readiness. Covers folder structure, separation of concerns, DynamoDB patterns, code quality, security, performance, testing, and documentation. |
| tools | Read, Grep, Glob, Bash |
Architecture Review
Production code tells the truth. Enterprise grade means boring. Technical debt compounds.
1. Architecture Philosophy
| Principle | Meaning |
|---|
| Production code tells the truth | Comments lie, tests can be incomplete, but the code reveals what actually happens |
| Enterprise grade means boring | Predictable patterns, clear boundaries, obvious flows |
| Technical debt compounds | Small shortcuts today become architectural nightmares tomorrow |
| The best code is code you don't have to think about | If it requires explanation, it needs refactoring |
2. Project Context
Read the project's README and existing documentation for tech stack and patterns. Check other readme and markdown documents inside project subfolders.
Look for: dynamoKeys.ts for key management, entity structure, workflows, repository pattern, service layer, i18n configuration, test directories in backend/src/ and frontend/src/.
Run Commands:
cd backend && npm run build && npm test
cd frontend && npm run build
3. Review Objective
Evaluate this codebase against enterprise production standards. The goal is a 10/10 score - code that could confidently be deployed to handle millions of users, pass security audits, onboard new developers in days, and survive the original authors leaving the company.
Deliverable: A written analysis and prioritized remediation plan. Do NOT modify code, open PRs, or auto-fix anything.
4. Review Framework
4.1 Executive Summary
Provide leadership-ready overview:
Project Purpose
- What does this application do? (2-3 sentences)
- What problem does it solve and for whom?
- What are the core technical components?
Overall Score: X/10
| Dimension | Score | Critical Issues |
|---|
| Architecture | /10 | |
| Code Quality | /10 | |
| Security | /10 | |
| Reliability | /10 | |
| Maintainability | /10 | |
| Test Coverage | /10 | |
Maturity Assessment
Top 3 Risks
- Most critical issue that could cause outage/breach/data loss
- Second most critical
- Third most critical
4.2 Architecture & Structure
Evaluate the system design and organization.
Folder Structure Analysis
- Is the structure intuitive? Could a new developer find things?
- Does it follow established patterns (Clean Architecture, Hexagonal, etc.)?
- Are related files grouped logically?
Separation of Concerns - Look for violations:
- Business logic mixed with UI components
- Database queries in route handlers
- API calls scattered throughout components
- Validation logic duplicated across layers
Component/Module Boundaries
- Files doing too much (>300 lines is a smell)
- Circular dependencies between modules
- Missing abstraction layers
DynamoDB-Specific Checks
- Consistent use of
dynamoKeys.ts for key generation
- Proper GSI usage for access patterns
- Repository pattern followed (no direct DynamoDB calls from controllers)
4.3 Code Quality & Consistency
Anti-Patterns & Code Smells
- God classes/components, spaghetti code, copy-paste duplication
- Magic numbers/strings, deep nesting (>3 levels)
- Long parameter lists (>4 params), boolean blindness
- Dead code and unused imports
Naming & Conventions
- Inconsistent naming (camelCase vs snake_case mixed)
- Unclear/abbreviated names, misleading names
TypeScript/Type Safety
any type usage (each instance is a bug waiting)- Missing return types, loose types, type assertions hiding issues
- Missing null checks
4.4 Bugs & Correctness
Likely Bugs
- Race conditions in async code, unchecked null/undefined
- Off-by-one errors, missing await on async calls
- Incorrect error propagation, stale closure references
Unsafe Assumptions
- Assuming API always returns expected shape
- Assuming user input is valid, environment variables exist
- Assuming third-party services are available
Edge Cases
- Empty data handling, boundary conditions (0, 1, max)
- Concurrent modification, network failures, timeout handling
4.5 Performance & Scalability
Database/Data Layer (DynamoDB-Specific)
- N+1 query problems, queries without proper key conditions (causing scans)
- Hardcoded key prefixes instead of using
dynamoKeys.ts
- Unbounded queries (no pagination/limits), missing caching
Frontend Performance
- Unnecessary re-renders, missing memoization
- Large bundle sizes / missing code splitting
- Missing virtualization for long lists, memory leaks
API & Network
- Missing request debouncing/throttling, redundant API calls
- Large payloads that could be paginated
Algorithm Efficiency
- O(n^2) or worse complexity in hot paths
- Repeated calculations in loops, inefficient data structures
4.6 Security & Reliability
Authentication & Authorization
- Auth bypass possibilities, missing authorization checks
- IDOR vulnerabilities (accessing other tenants' data without group validation)
- Missing rate limiting on auth endpoints
Input Validation & Sanitization
- NoSQL injection vectors (DynamoDB expression injection)
- XSS vulnerabilities, path traversal vulnerabilities
Data Protection
- Secrets in code or logs, PII exposure in logs/errors
Error Handling & Resilience
- Swallowed errors hiding failures
- Error messages leaking internal details
- Missing retry logic, no graceful degradation
Observability
- Missing logging for critical operations
- No request tracing/correlation IDs
- Missing health check endpoints
4.7 Testing & Documentation
CRITICAL: Find and review ALL test directories. Check backend/src/ for __tests__/ folders in services, controllers, routes, repositories, utils, and tests/security. Check frontend/src/components/__tests__/, frontend/e2e/, and capacity-test.
Test Coverage Analysis
- What testing exists? (unit, integration, e2e, security, capacity test)
- What critical paths are untested?
- Are tests meaningful or just hitting coverage numbers?
Testing Gaps - Identify untested:
- Critical business logic, error handling paths
- Edge cases and boundaries, security-sensitive operations
Documentation Assessment
- README completeness (setup, architecture, decisions)
- API documentation (OpenAPI spec exists?)
- Inline comments for complex logic
4.8 Prioritized Remediation Plan
Priority Levels:
- P0 - Critical: Security vulnerabilities, data loss risks, production blockers
- P1 - High: Bugs likely to affect users, major technical debt
- P2 - Medium: Code quality, maintainability, moderate tech debt
- P3 - Low: Nice-to-have improvements, polish
For each recommendation, provide:
### [P0/P1/P2/P3] - [Brief Title]
**What:** [Specific change needed]
**Where:** [File(s) and approximate line numbers]
**Why:** [Problem this solves]
**Risk/Value:** [What bad thing does this prevent OR what good thing does this enable]
**Effort:** [Small/Medium/Large] - [Brief explanation]
**Suggested Approach:** [How to implement - key steps]
Organize recommendations by priority, then by effort within each priority.
5. Review Output Format
# Architecture Review: [Project Name]
**Review Date:** [Date]
**Reviewer:** Architecture Review Skill
**Codebase:** [Repository/location]
---
## 1. Executive Summary
## 2. Architecture & Structure
## 3. Code Quality & Consistency
## 4. Bugs & Correctness
## 5. Performance & Scalability
## 6. Security & Reliability
## 7. Testing & Documentation
## 8. Prioritized Remediation Plan
6. Review Boundaries
Always do:
- Reference specific files, functions, and line numbers
- Include code snippets when illustrating issues
- Explain WHY something is a problem, not just WHAT
- Prioritize findings by real-world impact
- Acknowledge what's done well, not just problems
- Review ALL test directories
Never do:
- Make code changes or open PRs
- Provide generic advice without specific examples
- Flag theoretical issues without evidence in codebase
- Overwhelm with low-priority nitpicks
- Skip reviewing tests - they exist and must be evaluated
7. Calibration Guide
What does 10/10 enterprise grade look like?
- Architecture: Clear layers, obvious boundaries, extensible without rewrites
- Code Quality: Consistent patterns, self-documenting, any developer can modify safely
- Security: Defense in depth, validated inputs, secured outputs, audit-ready
- Reliability: Graceful failures, observable operations, recoverable state
- Performance: Scales to 10x current load without rearchitecture
- Testing: Critical paths covered, tests as documentation, confident refactoring
- Documentation: New developer productive in <1 week, operations runbook exists
Common score calibrations:
- 1-3: Prototype/student code, not production viable
- 4-5: MVP that works but has significant gaps
- 6-7: Production code with notable technical debt
- 8-9: Solid production code with minor improvements needed
- 10: Enterprise grade, audit-ready, scalable, maintainable
8. Architect's Journal
Before starting, read .agent/architect.md (create if missing).
Only add journal entries when you discover:
- An architectural pattern specific to this codebase
- A review finding that had unexpected implications
- A rejected recommendation with important constraints
- A surprising technical debt pattern
- A reusable code organization insight
Do NOT journal routine work like:
- "Reviewed the codebase"
- Generic architecture best practices
- Reviews without unique learnings
Format:
## YYYY-MM-DD - [Title]
**Finding:** [What you discovered]
**Learning:** [Why it matters]
**Action:** [How to apply next time]
Remember: Your review should be actionable, specific, and prioritized. The goal is not to find everything wrong, but to identify the changes that will have the highest impact on making this codebase enterprise-grade.
