comprehensive-architecture-review

This skill conducts a comprehensive, multi-phase architecture review of entire codebases. Perfect for onboarding, pre-refactor planning, technical debt assessment, or creating architectural decision records (ADRs).

7-Phase Workflow

Phase 1: Discovery & Purpose

Understand why we're reviewing the architecture:

Ask the user:

1. What's the purpose of this review?

   • Onboarding new team members?
   • Planning a major refactor?
   • Tech debt assessment?
   • Pre-acquisition due diligence?
   • Preparing for scale?

2. What concerns do you have? (if any)

   • Performance at scale?
   • Maintainability?
   • Onboarding difficulty?
   • Deployment complexity?
   • Security?

3. How old is this codebase?

   • When was it started?
   • Any major rewrites/migrations?
   • Original team still around?

4. What's the desired output?

   • Onboarding documentation?
   • Tech debt prioritization?
   • Refactoring roadmap?
   • ADR (Architectural Decision Record)?
   • All of the above?

Output:

## Architecture Review - Discovery

### Review Purpose
[Why we're doing this]

### Codebase Context
- Age: [time since start]
- History: [rewrites, migrations]
- Team: [original/new]

### Focus Areas
- [Priority 1]
- [Priority 2]
- [Priority 3]

### Known Concerns
- [Concern 1]
- [Concern 2]

### Deliverables
- [ ] [Deliverable 1]
- [ ] [Deliverable 2]

### Proceeding to Phase 2: Initial Exploration

Phase 2: Initial Exploration & Mapping

Quick scan to understand the codebase landscape:

Actions:

1. Project Structure

   • Identify project type (monorepo, polyglot, microservices, monolith)
   • Find package manager (package.json, requirements.txt, Cargo.toml, go.mod)
   • Locate configuration (tsconfig, webpack, vite, docker-compose)
   • Map directory structure

2. Technology Stack

   • Languages and versions
   • Frameworks
   • Databases
   • External services
   • Build tools

3. Dependency Scan

   • Count total dependencies
   • Identify critical deps
   • Check for outdated packages (if package manager supports)

4. Size & Complexity Metrics

   • Total lines of code (rough estimate)
   • Number of files
   • Module count
   • Test coverage (if available)

Output:

## Phase 2: Codebase Map

### Project Type
[Monolith/Microservices/Monorepo/Polyglot]

### Technology Stack
**Languages:**
- [Language 1]: [version]
- [Language 2]: [version]

**Frameworks:**
- [Framework 1]: [version]
- [Framework 2]: [version]

**Infrastructure:**
- Database: [type + version]
- Cache: [if applicable]
- Queue: [if applicable]
- Cloud: [AWS/GCP/Azure/on-prem]

### Codebase Metrics
- Files: ~[X]
- Estimated LoC: ~[Y]
- Dependencies: [Z] packages
- Tests: [W] files ([coverage]% if known)

### Directory Structure

project/ ├── src/ ([X] files) ├── tests/ ([Y] files) ├── config/ ├── docs/ └── ...

### Key Patterns Noticed
- [Pattern 1: e.g., Layered architecture in /src]
- [Pattern 2: e.g., Feature-based modules]
- [Red flag if any: e.g., No tests directory]

### Proceeding to Phase 3: Clarifying Questions

Phase 3: Clarifying Questions (🛑 CHECKPOINT)

IMPORTANT: Pause for targeted questions based on exploration.

Ask the user:

Architecture Understanding

1. Intended Architecture: What pattern were you aiming for?

   • Layered (MVC, Clean Architecture)?
   • Feature-based/Vertical slices?
   • Microservices/SOA?
   • Event-driven?
   • Other?

2. Boundaries: Are there clear module boundaries? Should there be?

3. Data Flow: How should data flow? (e.g., UI → Service → Repository → DB)

Technical Debt

1. Known Tech Debt: What do you already know is problematic?
2. TODO/HACK Comments: Want me to catalog these?
3. Deprecated Code: Any known deprecated patterns still in use?

Dependencies & Security

1. Dependency Tolerance: Okay with many deps, or prefer minimal?
2. Security Critical?: Need a security-focused review?
3. License Concerns: Any licensing requirements (e.g., no GPL)?

Scale & Performance

1. Current Scale: How many users/requests/data volume?
2. Growth Plans: Expected scale in 1 year? 3 years?
3. Performance SLAs: Any specific requirements?

Team & Process

1. Team Size: How many devs work on this?
2. Onboarding Pain: What's hardest for new devs to understand?
3. Deployment: How often do you deploy? How long does it take?

📋 Present Initial Findings:

• "I see [X] dependencies, [Y] are >2 years old. Should I audit these?"
• "Directory structure suggests [pattern], but code shows [different pattern]. Should I investigate the mismatch?"
• "No obvious API documentation. Should I check for this?"

Ask about depth:

• "Deep dive into dependency security?"
• "Map out all circular dependencies?"
• "Document every architectural pattern found?"

Wait for user responses.

Phase 4: Deep Analysis with Gemini

Based on user priorities, run comprehensive Gemini analysis:

Verify Gemini CLI:

which gemini || echo "Please install Gemini CLI"

Construct Analysis Prompt (highly customized based on Phase 3):

gemini -p "@. --ignore node_modules,.git,dist,build,coverage,.next,.cache

You are a Software Architect conducting a deep review with these priorities:

[INSERT USER PRIORITIES FROM PHASE 3]

Analyze this ENTIRE codebase for:

## 1. Project Structure & Organization (Priority: [from user])

- Directory organization effectiveness
- Module boundaries and cohesion
- Circular dependency risks (flag any)
- Import/export patterns
- **Compare to stated architecture**: [user's intended pattern]
- Deviations from [stated architecture]

## 2. Dependency Analysis (Priority: [from user])

- Critical dependencies (frameworks, databases, auth)
- Outdated packages (>2 years old)
- Duplicate functionality across deps
- Security-sensitive dependencies
- Bundle size contributors (if frontend)
- Licensing issues (if user cares: [from Phase 3])

**Dependencies to scrutinize:**
- [User-specified concerns from Phase 3]

## 3. Architecture Patterns (Priority: [from user])

- Layering and separation of concerns
- API design patterns (REST, GraphQL, RPC?)
- Error handling strategy (consistent?)
- Configuration management approach
- Environment handling (dev, staging, prod)
- Logging & observability patterns
- **Expected scale**: [from user's Phase 3 answer]
- **Scalability assessment**: Will this handle [user's growth plans]?

## 4. Technical Debt (Priority: [from user])

- TODO/FIXME/HACK comments (catalog with context)
- Known deprecated patterns: [from user's list]
- Dead code detection
- Inconsistent patterns across modules
- Missing abstractions (code duplication >3 instances)
- [User's known tech debt items to investigate]

## 5. Testing Architecture (Priority: [from user])

- Test organization and patterns
- Coverage gaps (which areas untested?)
- Missing test categories (unit, integration, e2e?)
- Test quality (brittleness, over-mocking)
- Test utility patterns

## 6. Build & Deploy Infrastructure (Priority: [from user])

- Build configuration (complexity, optimization)
- Environment-specific configs
- CI/CD patterns (if config files present)
- Deployment approach (containers, serverless, traditional?)
- **Current deployment**: [user's answers from Phase 3]
- **Bottlenecks**: What slows deployment?

## 7. Security Considerations (if priority: [from user])

- Auth/authz patterns
- Secret management
- Input validation approaches
- Dependency vulnerabilities

## 8. Onboarding & Documentation (if priority: [from user])

- README quality
- Inline documentation
- Architecture diagrams (present?)
- Setup instructions clarity
- **Onboarding pain points to address**: [from user's Phase 3 answer]

**Output Format:**
- Executive summary (1 paragraph)
- Score per category (X/10)
- Specific issues with file:line references
- Architectural Decision Record style: What decisions were made, why (infer), consequences
- Prioritize findings by [user's criteria from Phase 3]
"

Parse and Structure Gemini Analysis:

## Phase 4: Deep Architecture Analysis

### Executive Summary
[1-2 paragraph overview of codebase health and key findings]

### Architecture Health Score: X/10

---

#### Project Structure (Score: Y/10)

**Strengths:**
- [Positive finding 1]
- [Positive finding 2]

**Concerns:**
- 🔴 Circular dependencies detected:
  - `src/services/auth.ts` ↔ `src/models/user.ts`
  - `src/components/Dashboard.tsx` ↔ `src/hooks/useDashboard.ts`
  - **Impact**: Makes testing difficult, increases coupling
  - **Recommendation**: Introduce `src/types/user.ts` for shared types

- 🟡 Module boundaries unclear:
  - Feature modules in `src/features` but also in `src/pages`
  - **Recommendation**: Standardize on one approach

**Pattern Analysis:**
- Intended: [User's stated architecture]
- Actual: [What we found]
- **Gap**: [Deviations and why they matter]

---

#### Dependency Health (Score: Z/10)

**Critical Dependencies:**
- `react@18.2.0` - Core framework
- `express@4.18.2` - API server
- `postgres@3.3.4` - Database
- [Others]

**Outdated (>2 years):**
- 🔴 `lodash@4.17.20` (2020) - Consider native ES6+ or upgrade
- 🟡 `moment@2.29.1` (2020) - Deprecated, migrate to date-fns or Day.js

**Duplicates:**
- Date handling: `moment` + `date-fns` (both do the same thing)
- HTTP clients: `axios` + `fetch` wrapper + `got`
  - **Recommendation**: Standardize on one

**Security Concerns:**
- [Any vulnerable deps]

**Bundle Impact** (if frontend):
- `lodash`: +70KB (use lodash-es or individual imports)
- `moment`: +230KB (migrate to lighter alternative)

---

#### Architecture Patterns (Score: W/10)

**Layering:**
- [What we found]
- **Adherence to [stated pattern]**: [Good/Mixed/Poor]

**API Design:**
- [RESTful/GraphQL/Mixed]
- **Consistency**: [Assessment]

**Error Handling:**
- [Consistent/Inconsistent]
- **Gaps**: [Areas with poor error handling]

**Configuration:**
- Environment: [How it's managed]
- **Concerns**: [Any hardcoded configs, missing env vars]

**Scalability Assessment:**
- **Current**: [User's current scale]
- **Target**: [User's growth plans]
- **Bottlenecks**:
  - [Bottleneck 1: e.g., Single DB connection pool]
  - [Bottleneck 2: e.g., Synchronous processing]
- **Recommendations**: [How to prepare for scale]

---

#### Technical Debt Inventory (Score: Q/10)

**TODO/FIXME/HACK Comments:**
- Total: [X] instances
- **High Priority** (with "URGENT", "FIXME", "HACK"):
  - `src/auth/oauth.ts:45`: "HACK: Temporary fix for token refresh race condition"
  - `src/api/products.ts:123`: "TODO: Add proper error handling before launch"
  - [5 more...]

**Deprecated Patterns Still in Use:**
- [User-mentioned deprecated items + what we found]

**Dead Code:**
- `src/legacy/` directory (7 files) - Not imported anywhere
- `OldDashboard.tsx` - Replaced by `DashboardV2.tsx`
- [Estimate]: ~[X]% of codebase is dead code

**Code Duplication:**
- Similar user validation logic in 4 places (files: [list])
- Database query patterns repeated 12 times
- **Opportunity**: Extract to shared utilities

**Inconsistent Patterns:**
- Error handling: Some use try/catch, some use callbacks, some return errors
- API calls: 3 different patterns across the codebase
- State management: Mix of Context, Redux, and local state with no clear rule

---

#### Testing Architecture (Score: R/10)

**Coverage**: [X]% (via coverage reports if found)

**Organization:**
- [How tests are structured]

**Gaps:**
- Untested areas: [list critical areas]
- Missing integration tests for [areas]
- No e2e tests found

**Test Quality:**
- [Assessment of test brittleness, over-mocking, etc.]

---

#### Build & Deploy (Score: S/10)

**Build Configuration:**
- Tool: [Webpack/Vite/Turbopack/etc.]
- **Complexity**: [Simple/Moderate/Complex]
- **Optimization**: [Good/Could improve]

**Deployment:**
- Approach: [Docker/Serverless/Traditional]
- **User-reported duration**: [from Phase 3]
- **Bottlenecks identified**: [from config analysis]

**Environment Handling:**
- [How dev/staging/prod are managed]
- **Concerns**: [Any issues]

---

### Proceeding to Phase 5: ADR & Recommendations

Phase 5: Architectural Decision Record & Recommendations (🛑 CHECKPOINT)

Present findings as an ADR and offer improvement paths:

Generate ADR:

## Architectural Decision Record (ADR)

### Context

This codebase is a [type] application built with [stack], started [time ago]. It serves [purpose] and handles [scale].

### Key Architectural Decisions (Inferred & Documented)

#### Decision 1: [e.g., Monolithic Architecture]
**Why (Inferred)**: Early-stage product, small team, need for rapid iteration
**Consequences**:
- ✅ Fast development initially
- ✅ Simple deployment
- ⚠️ Now facing scaling challenges as [area] grows
- ⚠️ Difficult to parallelize team work

**Current State**: Monolith is ~[X] LoC, deployment takes [Y] min
**Future Consideration**: May need to extract [service] as microservice when [metric] exceeds [threshold]

#### Decision 2: [e.g., [Framework] for Frontend]
**Why**: [Inferred reasons]
**Consequences**: [Trade-offs]

[...more decisions...]

### Technical Debt Assessment

**Total Debt Estimate**: [High/Medium/Low]

**High-Impact Debt** (Fix Soon):
1. [Item 1 from analysis]
2. [Item 2]
3. [Item 3]

**Medium-Impact Debt** (Plan to Address):
[List]

**Low-Impact Debt** (Monitor):
[List]

Present Improvement Options:

Option A: Onboarding Documentation Focus

• Create architecture overview doc
• Document key patterns and conventions
• Write setup guide addressing [user's pain points]
• Effort: [X days]
• Output: Comprehensive onboarding materials

Option B: Technical Debt Remediation

• Address high-impact debt items
• Modernize outdated dependencies
• Clean up [X]% dead code
• Effort: [Y weeks]
• Output: Healthier, more maintainable codebase

Option C: Scalability Preparation

• Address identified bottlenecks for [user's growth plans]
• Refactor for scale (caching, async processing, DB optimization)
• Set up performance monitoring
• Effort: [Z weeks]
• Output: Codebase ready for [target scale]

Option D: Architecture Realignment

• Align actual implementation with [intended architecture]
• Fix circular dependencies
• Standardize patterns
• Effort: [W months]
• Output: Codebase that matches architectural intent

Ask user:

I've documented the architectural decisions and assessed tech debt.

Which path forward?
- A) Create onboarding docs
- B) Remediate tech debt
- C) Prepare for scale
- D) Realign architecture
- E) Combination (let's discuss priorities)

Or should I:
- Deep dive into [specific area]?
- Generate dependency upgrade plan?
- Create refactoring roadmap for [specific concern]?
- Compare your architecture to [similar project pattern]?

Wait for user decision.

Phase 6: Action Plan & Roadmap

Based on user's choice, create detailed plan:

## Phase 6: Action Plan - [User's Chosen Path]

### Immediate Actions (Week 1)

#### [If Onboarding Docs Chosen]
- [ ] Create `ARCHITECTURE.md`
  - System overview diagram
  - Tech stack with versions and rationale
  - Directory structure guide
  - Key patterns and conventions
  - Data flow diagrams
  - Deployment architecture

- [ ] Create `ONBOARDING.md`
  - Prerequisites
  - Setup steps (address [user's pain points])
  - Running locally guide
  - Common issues and solutions
  - First task suggestions

- [ ] Document API contracts
  - [If applicable]

[...detailed checklist...]

#### [If Tech Debt Remediation Chosen]
**Priority 1: High-Impact Debt**
- [ ] Fix critical circular dependency: auth ↔ user
  - Create `src/types/user.ts`
  - Move shared types
  - Update imports in auth.ts and user.ts
  - **Effort**: 2h | **Risk**: Low | **Test**: [affected tests]

- [ ] Remove dead code (~[X]% of codebase)
  - Delete `src/legacy/` (verified unused)
  - Remove OldDashboard.tsx (replaced)
  - Clean up unused imports
  - **Effort**: 4h | **Impact**: Clearer codebase, faster builds

- [ ] Upgrade outdated deps (focus on security-critical first)
  - [List with upgrade paths]

[...detailed tasks with effort, risk, breaking change flags...]

#### [If Scalability Prep Chosen]
**Bottleneck 1: Database Connection Pool**
- Current: Single connection pool, limiting to ~100 concurrent users
- Target: Support [user's growth plan]
- Solution: Implement connection pooling with [tool]
- Effort: [X days]

[...more bottleneck fixes...]

#### [If Architecture Realignment Chosen]
[Refactoring roadmap to match intended architecture]

### Success Metrics
- [ ] [Metric 1 based on goals]
- [ ] [Metric 2]
- [ ] [Metric 3]

### Timeline
- **Week 1-2**: [Tasks]
- **Month 1**: [Milestones]
- **Quarter 1**: [Goals]

Ask user:

Does this plan match your expectations?

Should I:
- Start creating documentation?
- Generate specific code examples for refactoring?
- Create GitHub issues for each task?
- Adjust priorities?

Phase 7: Summary & Deliverables

## Architecture Review - Summary

### What We Analyzed
- **Entire codebase**: [X] files, ~[Y] LoC
- **Dependencies**: [Z] packages
- **Architecture patterns**: [patterns found]

### Key Findings

1. **Structure** (Score: [X]/10)
   - [Summary of findings]

2. **Dependencies** (Score: [Y]/10)
   - [Outdated], [duplicates], [concerns]

3. **Architecture** (Score: [Z]/10)
   - [Alignment with intent], [scalability]

4. **Technical Debt** (Impact: [HIGH/MEDIUM/LOW])
   - [Key debt items]

5. **Testing** (Coverage: [W]%)
   - [Gaps and quality]

6. **Build/Deploy**
   - [Findings]

### Architectural Decisions Documented
- [Decision 1]
- [Decision 2]
- [...]

### Path Chosen
[User's selected approach with rationale]

### Deliverables
- [X] Architectural Decision Record (ADR)
- [X] Health scores per category
- [X] Tech debt inventory ([N] items)
- [X] [Chosen deliverable: onboarding docs/refactoring plan/scaling roadmap]
- [ ] [In progress/pending deliverables]

### Next Steps
1. [Immediate action]
2. [Short-term goal]
3. [Long-term vision]

### Recommended Re-review
- [Timeframe based on codebase age and velocity]

---

**Architecture review completed using Gemini CLI analyzing [X]M tokens across entire codebase**

Special Features

Comparison Analysis

At any phase, user can request:

• "Compare our architecture to [framework]'s best practices"
• "How does this compare to [similar project]?"
• "What would [architecture pattern] look like here?"

Triggers focused Gemini analysis with reference architecture.

Dependency Upgrade Planning

Can generate:

• Dependency upgrade roadmap
• Breaking change analysis
• Incremental upgrade strategy

Visualization Support

Offer to create (with user approval):

• Architecture diagrams (as code with Mermaid/PlantUML)
• Dependency graphs
• Data flow diagrams

Integration

Can generate:

• GitHub issues per debt item
• ADR markdown files for /docs
• Onboarding materials
• Team wiki pages

Key Principles

1. Comprehensive: Gemini analyzes ENTIRE codebase, no sampling
2. Contextual: Decisions viewed through lens of team size, scale, age
3. Practical: Recommendations match team capacity
4. Honest: Both strengths and weaknesses documented
5. Forward-Looking: Plans account for growth trajectory

This ensures architecture reviews are thorough, actionable, and produce valuable documentation for teams.