Back to catalog

analyze-architecture

Prioritized recommendations

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• GitHub stars: 1
• Updated: 2025-11-21

• Source: adolfoaranaes12/BMAD-ENHANCED

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: analyze-architecture
description: Comprehensive brownfield architecture analysis for existing codebases. Discovers structure, identifies patterns, assesses quality, calculates production readiness, and provides actionable recommendations. Use when analyzing existing codebases to understand architecture, assess quality, or prepare for modernization.
acceptance:
  - codebase_structure_analyzed: "Codebase structure discovered and documented"
  - project_type_detected: "Project type identified (frontend/backend/fullstack/monorepo)"
  - architecture_patterns_identified: "Architectural patterns recognized and documented"
  - tech_stack_documented: "Technology stack analyzed with versions"
  - quality_scores_calculated: "Quality scores computed across 8 dimensions"
  - production_readiness_scored: "Production readiness score calculated (0-100)"
  - recommendations_provided: "Actionable recommendations prioritized by impact"
  - report_generated: "Comprehensive analysis report generated"
inputs:
  codebase_path:
    type: string
    required: false
    description: "Path to codebase root (default: current directory)"
  output_format:
    type: string
    required: false
    description: "markdown | json | both (default: markdown)"
  focus_area:
    type: string
    required: false
    description: "architecture | security | performance | scalability | tech-debt | all (default: all)"
  depth:
    type: string
    required: false
    description: "quick | standard | comprehensive (default: standard)"
  token_budget:
    type: number
    required: false
    description: "Maximum tokens to use (default: 100000)"
outputs:
  report_file:
    type: string
    description: "Path to generated analysis report"
  project_type:
    type: string
    description: "Detected project type"
  architecture_patterns:
    type: array
    description: "List of identified architectural patterns"
  production_readiness_score:
    type: number
    description: "Overall production readiness score (0-100)"
  quality_scores:
    type: object
    description: "Quality scores per dimension"
  tech_debt_items:
    type: array
    description: "Identified technical debt items"
  recommendations:
    type: array
    description: "Prioritized recommendations"
telemetry:
  emit: "skill.analyze-architecture.completed"
  track:
    - project_type
    - architecture_patterns
    - production_readiness_score
    - tech_debt_count
    - recommendations_count
    - duration_ms
    - focus_area
---

# Analyze Architecture (Brownfield)

## Purpose

Perform comprehensive, production-ready architecture analysis of existing codebases. Designed for brownfield projects where formal architecture documentation may not exist. Discovers structure, identifies patterns, assesses quality across 8 dimensions, and provides actionable recommendations.

**Core Principles:**
- **Discovery-first:** Understand what exists before judging
- **Pattern recognition:** Identify architectural patterns in use
- **Multi-dimensional:** Quality assessment across 8 key areas
- **Actionable insights:** Prioritized recommendations with effort estimates
- **Production focus:** Calculate readiness for production deployment
- **Brownfield-optimized:** Works without existing documentation

---

## Prerequisites

- Codebase accessible on filesystem
- Read access to all source files
- Build configuration files present (package.json, etc.)
- Database schema files accessible (if applicable)

---

## Workflow Modes

Choose the analysis depth based on time constraints and requirements:

### Quick Mode (`--depth quick`)
**Duration:** 5-7 minutes
**Token Usage:** ~50,000 tokens
**Steps:** 1-8 only
**Output:** Executive summary + key metrics

**Best For:**
- Initial assessments
- Time-sensitive decisions
- High-level overviews
- Quick health checks

**Steps Included:**
1. Discover Codebase Structure
2. Detect Project Type
3. Analyze Technology Stack
4. Identify Architectural Patterns
5. Calculate Quality Scores (simplified)
6. Identify Critical Technical Debt
7. Generate Quick Report
8. Emit Telemetry

---

### Standard Mode (`--depth standard`) [DEFAULT]
**Duration:** 10-12 minutes
**Token Usage:** ~80,000 tokens
**Steps:** 1-12
**Output:** Comprehensive analysis without deep-dives

**Best For:**
- Regular assessments
- Pre-production reviews
- Architecture validation
- Team presentations

**Steps Included:**
1-11 from full workflow (excludes integration analysis, deep testing review, and extended report sections)

---

### Comprehensive Mode (`--depth comprehensive`)
**Duration:** 15-20 minutes
**Token Usage:** ~120,000 tokens
**Steps:** All 15 steps
**Output:** Complete analysis with all sections

**Best For:**
- Production readiness assessments
- Architecture audits
- Documentation creation
- Detailed planning

**Steps Included:**
All 15 steps with deep analysis, complete recommendations, risk assessment, and extended report

---

## Adaptive Workflow

The skill automatically adapts based on available information:

**Early Exit Conditions:**
- If `docs/architecture.md` exists and is recent (<30 days): Reference existing documentation, skip redundant discovery
- If all package.json files parsed successfully: Skip manual tech stack discovery
- If documentation is comprehensive: Validate metrics instead of rediscovering

**Token Budget Management:**
- Track token usage per step
- Warn at 80% of budget
- Switch to quick mode if budget exceeded
- Prioritize critical findings if limited budget

---

## Workflow

### 1. Discover Codebase Structure

**Action:** Analyze directory structure and identify key components

**Early Exit Condition:**
If `docs/architecture.md` or `docs/ARCHITECTURE.md` exists and is recent (<30 days):
- Read existing architecture documentation
- Extract project structure from docs
- Validate structure still matches (quick check)
- Skip to Step 4 (Architectural Patterns)

**Execute:**
```bash
# Check for existing architecture docs
find {codebase_path}/docs -name "*architecture*.md" -mtime -30 2>/dev/null

# If no recent docs, discover structure
# Find all major directories and files
find {codebase_path} -maxdepth 3 -type d | head -50
find {codebase_path} -name "package.json" -o -name "*.config.*" -o -name "tsconfig.json"
```

**Identify:**
- **Monorepo detection:** Multiple package.json files, workspaces config
- **Package structure:** packages/, apps/, libs/, src/ directories
- **Configuration files:** tsconfig.json, .eslintrc, vite.config.ts, etc.
- **Documentation:** README.md, docs/ folder, ARCHITECTURE.md
- **Build artifacts:** dist/, build/, node_modules/

**Classification:**
- **Monorepo:** Multiple packages with shared configuration
- **Standalone:** Single package with unified source
- **Microservices:** Multiple independent services
- **Modular monolith:** Single codebase with clear module boundaries

**See:** `references/codebase-discovery-guide.md` for detection heuristics

---

### 2. Detect Project Type

**Action:** Determine primary domain (frontend, backend, fullstack, monorepo)

**Frontend indicators:**
- React, Vue, Angular, Svelte dependencies
- Component directories (components/, pages/, views/)
- State management (Redux, Zustand, Pinia)
- UI libraries (Material-UI, TailwindCSS, shadcn)
- Build tools (Vite, Webpack, Next.js)

**Backend indicators:**
- Express, Fastify, NestJS, Koa dependencies
- API routes (routes/, controllers/, endpoints/)
- Database ORM (Prisma, TypeORM, Sequelize)
- Service layers (services/, handlers/, use-cases/)
- Middleware (auth, validation, error handling)

**Fullstack indicators:**
- Next.js, Remix, SvelteKit, Nuxt
- Both frontend and backend patterns present
- API routes within same codebase
- Shared types between client/server

**Monorepo indicators:**
- Workspaces in package.json (npm, yarn, pnpm)
- Turborepo, Nx, Lerna configuration
- Multiple packages with dependencies
- Shared libraries and utilities

**Output:** `project_type` = frontend | backend | fullstack | monorepo

---

### 3. Analyze Technology Stack

**Action:** Extract and document all technologies with versions

**Early Exit Condition:**
If all package.json files found and successfully parsed:
- Extract dependencies and devDependencies
- Parse versions directly from package.json
- Skip manual grep-based discovery
- Proceed to Step 4

**Execute:**
```bash
# Read all package.json files
find {codebase_path} -name "package.json" -not -path "*/node_modules/*" -exec cat {} \;

# Extract tech stack using primitive (preferred)
python .claude/skills/bmad-commands/scripts/extract_tech_stack.py \
  --codebase {codebase_path} \
  --output json

# Read Prisma schema if exists
find {codebase_path} -name "schema.prisma" -exec cat {} \;
```

**Extract:**

**Backend Stack:**
- Runtime (Node.js version from .nvmrc or package.json)
- Framework (Express, NestJS, Fastify, etc.)
- ORM/Database (Prisma, TypeORM, Mongoose, etc.)
- Caching (Redis, Memcached)
- Job queues (Bull, Inngest, Agenda)
- Auth (Passport, JWT, Clerk, Auth0)
- Validation (Zod, Joi, Yup)
- Testing (Jest, Vitest, Mocha)

**Frontend Stack:**
- Framework (React, Vue, Angular, Svelte)
- UI Library (Material-UI, Ant Design, Chakra)
- State Management (Redux, Zustand, Recoil, Context)
- Data Fetching (React Query, SWR, Apollo)
- Routing (React Router, Vue Router)
- Styling (CSS-in-JS, Tailwind, CSS Modules)
- Build Tool (Vite, Webpack, Rollup)
- Testing (Vitest, Jest, Playwright, Cypress)

**Database & Infrastructure:**
- Database (PostgreSQL, MongoDB, MySQL, etc.)
- Caching layer (Redis, Memcached)
- Search (Elasticsearch, Algolia)
- File storage (S3, Cloudinary, Supabase)
- Real-time (WebSocket, SSE, Socket.io)

**DevOps & Tools:**
- Package manager (npm, yarn, pnpm)
- Monorepo tool (Turborepo, Nx, Lerna)
- CI/CD (GitHub Actions, CircleCI, etc.)
- Linting (ESLint, Prettier)
- Type checking (TypeScript)

**Output:** Complete technology inventory with versions

**See:** `references/tech-stack-catalog.md` for common patterns

---

### 4. Identify Architectural Patterns

**Action:** Recognize and document architectural patterns in use

**Search for pattern indicators:**

**Domain-Driven Design (DDD):**
```bash
# Look for DDD structure
grep -r "domain/entities" {codebase_path}/src
grep -r "domain/value-objects" {codebase_path}/src
grep -r "AggregateRoot" {codebase_path}/src
grep -r "DomainEvent" {codebase_path}/src
```

**CQRS (Command Query Responsibility Segregation):**
```bash
# Use metric validation primitive for accuracy (RECOMMENDED)
python .claude/skills/bmad-commands/scripts/validate_metrics.py \
  --codebase {codebase_path}/src \
  --metric cqrs \
  --output json

# Alternative: Manual discovery (less accurate)
# grep -r "CommandHandler" {codebase_path}/src
# grep -r "QueryHandler" {codebase_path}/src
# find {codebase_path}/src -path "*/commands/*" -o -path "*/queries/*"
```

**Expected Output:**
```json
{
  "command_files": 92,
  "query_files": 119,
  "command_handlers": 65,
  "query_handlers": 87,
  "total_handlers": 152,
  "total_files": 211
}
```

**Layered Architecture:**
```bash
# Look for layers
find {codebase_path}/src -type d -name "presentation" -o -name "application" -o -name "domain" -o -name "infrastructure"
find {codebase_path}/src -type d -name "controllers" -o -name "services" -o -name "repositories"
```

**Microservices:**
```bash
# Look for service boundaries
find {codebase_path} -name "docker-compose.yml" -o -name "Dockerfile"
find {codebase_path}/services -type d -maxdepth 1
```

**Event-Driven:**
```bash
# Look for event patterns
grep -r "EventEmitter" {codebase_path}/src
grep -r "EventBus" {codebase_path}/src
find {codebase_path}/src -path "*/events/*"
```

**Hexagonal/Ports & Adapters:**
```bash
# Look for ports and adapters
find {codebase_path}/src -path "*/ports/*" -o -path "*/adapters/*"
grep -r "interface.*Port" {codebase_path}/src
```

**Repository Pattern:**
```bash
# Look for repositories
find {codebase_path}/src -path "*/repositories/*"
grep -r "Repository" {codebase_path}/src | grep -E "(class|interface)"
```

**Output:** Array of identified patterns with evidence

**Pattern Confidence Scoring:**
- Strong evidence: 5+ files matching pattern
- Moderate evidence: 3-4 files matching pattern
- Weak evidence: 1-2 files matching pattern

**See:** `references/architectural-patterns-catalog.md` for complete list

---

### 5. Evaluate Domain Model (if DDD/CQRS)

**Action:** Analyze domain entities, services, and events

**Discover Entities:**
```bash
# Find entity files
find {codebase_path}/src -path "*/domain/entities/*" -o -path "*/entities/*"
grep -r "class.*Entity" {codebase_path}/src
```

**Discover Value Objects:**
```bash
# Find value objects
find {codebase_path}/src -path "*/domain/value-objects/*" -o -path "*/value-objects/*"
```

**Discover Aggregates:**
```bash
# Find aggregate roots
grep -r "AggregateRoot" {codebase_path}/src
```

**Discover Domain Events:**
```bash
# Find domain events
find {codebase_path}/src -path "*/domain/events/*" -o -path "*/events/*"
grep -r "DomainEvent" {codebase_path}/src
```

**Discover Application Services:**
```bash
# Find services
find {codebase_path}/src -path "*/application/services/*" -o -path "*/services/*"
grep -r "class.*Service" {codebase_path}/src | head -20
```

**Discover Command/Query Handlers:**
```bash
# Find CQRS handlers
find {codebase_path}/src -path "*/handlers/commands/*" -o -path "*/handlers/queries/*"
grep -r "CommandHandler\|QueryHandler" {codebase_path}/src | wc -l
```

**Output:**
- Entity count and list
- Value object count
- Aggregate roots identified
- Domain events count
- Service count
- Command handler count
- Query handler count

**Domain Model Quality Indicators:**
- **Excellent:** Clear separation, proper aggregates, rich domain logic
- **Good:** Entities present, some business logic in domain
- **Fair:** Anemic domain model, logic in services
- **Poor:** No domain layer, data structures only

---

### 6. Assess API Architecture

**Action:** Analyze API design, endpoints, and middleware

**Discover API Endpoints:**
```bash
# Find route definitions
find {codebase_path}/src -path "*/routes/*" -o -path "*/controllers/*"
grep -r "router\." {codebase_path}/src | grep -E "(get|post|put|patch|delete)" | wc -l
```

**Identify API Style:**
- **REST:** router.get(), router.post(), /api/v1/ patterns
- **GraphQL:** schema definitions, resolvers, apollo-server
- **tRPC:** .query(), .mutation(), typed procedures
- **gRPC:** .proto files, protobuf definitions

**Discover Middleware:**
```bash
# Find middleware
find {codebase_path}/src -path "*/middleware/*"
grep -r "app.use\|router.use" {codebase_path}/src
```

**Common Middleware to Check:**
- Authentication (JWT verification, OAuth)
- Authorization (RBAC, permissions)
- Validation (request body/params validation)
- Error handling (global error handler)
- Rate limiting (DDoS protection)
- Request logging (audit trail)
- CORS (cross-origin handling)

**API Versioning:**
```bash
# Check for versioning
grep -r "/api/v[0-9]" {codebase_path}/src
```

**Output:**
- API style (REST, GraphQL, tRPC, gRPC)
- Endpoint count
- Middleware stack
- Versioning strategy
- Authentication method
- Authorization approach

**API Quality Indicators:**
- **Excellent:** Versioned, validated, authenticated, documented
- **Good:** Proper middleware, error handling, basic validation
- **Fair:** Basic routes, some middleware missing
- **Poor:** No middleware, no validation, security gaps

---

### 7. Review Data Architecture

**Action:** Analyze database schema, caching, and real-time infrastructure

**Analyze Database Schema:**
```bash
# Find Prisma schema
find {codebase_path} -name "schema.prisma" -exec wc -l {} \;
find {codebase_path} -name "schema.prisma" -exec grep -E "model |enum " {} \; | wc -l

# Find migrations
find {codebase_path} -path "*/prisma/migrations/*" -name "migration.sql" | wc -l
```

**Extract from Schema:**
- Model count (database tables)
- Enum count (type enums)
- Relationship patterns (one-to-many, many-to-many)
- Index count (performance indexes)
- Multi-tenancy patterns (tenantId fields)

**Check Caching Strategy:**
```bash
# Look for caching
grep -r "redis\|cache\|memcache" {codebase_path}/src --include="*.ts" | wc -l
find {codebase_path}/src -path "*/cache/*"
```

**Identify Real-time Architecture:**
```bash
# Look for real-time
grep -r "WebSocket\|SSE\|socket.io\|EventSource" {codebase_path}/src
find {codebase_path}/src -path "*/realtime/*"
```

**Output:**
- Database type (PostgreSQL, MongoDB, etc.)
- Model count
- Index optimization level
- Multi-tenant design (yes/no)
- Caching strategy (Redis, in-memory, none)
- Real-time approach (WebSocket, SSE, polling, none)

**Data Architecture Quality Indicators:**
- **Excellent:** Optimized indexes, caching, multi-tenant, real-time
- **Good:** Proper schema, some indexes, basic caching
- **Fair:** Basic schema, missing indexes, no caching
- **Poor:** Unoptimized schema, no indexes, performance issues

---

### 8. Analyze Security Posture

**Action:** Assess authentication, authorization, and security measures

**Authentication Analysis:**
```bash
# Find auth implementation
grep -r "passport\|jwt\|clerk\|auth0\|supabase" {codebase_path}/src
find {codebase_path}/src -path "*/auth/*"
```

**Authorization Analysis:**
```bash
# Find authorization logic
grep -r "RBAC\|permissions\|roles\|authorize" {codebase_path}/src
grep -r "canAccess\|hasPermission\|checkRole" {codebase_path}/src
```

**Security Measures Check:**
```bash
# Check for security practices
grep -r "helmet\|cors\|csurf\|express-rate-limit" {codebase_path}/src
grep -r "bcrypt\|argon2\|scrypt" {codebase_path}/src
grep -r "sanitize\|escape\|validator" {codebase_path}/src
```

**Secrets Management:**
```bash
# Check for environment variables and secrets
find {codebase_path} -name ".env*" | wc -l
grep -r "process.env" {codebase_path}/src | wc -l
grep -r "AWS_SECRET\|API_KEY\|PASSWORD" {codebase_path}/src
```

**SQL Injection Protection:**
- Prisma (parameterized queries) = Protected
- Raw SQL queries = Vulnerable
- Input validation with Zod/Joi = Protected

**XSS Protection:**
- React (JSX escaping) = Protected
- Helmet CSP headers = Protected
- User input sanitization = Protected

**Output:**
- Authentication method (JWT, OAuth, Clerk, etc.)
- Authorization approach (RBAC, ABAC, etc.)
- Security headers (Helmet, CORS, CSP)
- Password hashing (bcrypt, argon2)
- Input validation (Zod, Joi, Yup)
- SQL injection protection (ORM usage)
- XSS protection (React, sanitization)
- Secrets management (env vars, vault)

**Security Score Calculation:**
- Auth present: 20 points
- Authorization (RBAC): 15 points
- Security headers: 15 points
- Password hashing: 10 points
- Input validation: 15 points
- SQL injection protected: 10 points
- XSS protection: 10 points
- Secrets properly managed: 5 points
- **Total:** 0-100

---

### 9. Evaluate Performance Characteristics

**Action:** Identify bottlenecks and optimization opportunities

**Database Performance:**
```bash
# Check for indexes
grep -r "@@index\|@@id\|@@unique" {codebase_path}/prisma/schema.prisma | wc -l

# Look for N+1 query patterns
grep -r "findMany\|findFirst" {codebase_path}/src | wc -l
grep -r "include:\|select:" {codebase_path}/src | wc -l
```

**Caching Strategy:**
```bash
# Check caching implementation
grep -r "redis.get\|cache.get" {codebase_path}/src | wc -l
grep -r "redis.set\|cache.set" {codebase_path}/src | wc -l
```

**Frontend Performance:**
```bash
# Check for code splitting
grep -r "React.lazy\|lazy(" {codebase_path}/src
grep -r "dynamic(.*import" {codebase_path}/src

# Check for memoization
grep -r "useMemo\|useCallback\|React.memo" {codebase_path}/src | wc -l
```

**Query Optimization:**
- Proper indexes present: +20 points
- Connection pooling configured: +10 points
- Caching implemented: +20 points
- Code splitting: +10 points
- Memoization used: +10 points

**Output:**
- Database index count
- Caching strategy (Redis