Analyze Architecture

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:

# 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:

# 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):

# 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):

# 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:

{
  "command_files": 92,
  "query_files": 119,
  "command_handlers": 65,
  "query_handlers": 87,
  "total_handlers": 152,
  "total_files": 211
}

Layered Architecture:

# 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:

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

Event-Driven:

# 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:

# Look for ports and adapters
find {codebase_path}/src -path "*/ports/*" -o -path "*/adapters/*"
grep -r "interface.*Port" {codebase_path}/src

Repository Pattern:

# 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:

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

Discover Value Objects:

# Find value objects
find {codebase_path}/src -path "*/domain/value-objects/*" -o -path "*/value-objects/*"

Discover Aggregates:

# Find aggregate roots
grep -r "AggregateRoot" {codebase_path}/src

Discover Domain Events:

# Find domain events
find {codebase_path}/src -path "*/domain/events/*" -o -path "*/events/*"
grep -r "DomainEvent" {codebase_path}/src

Discover Application Services:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

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

Authorization Analysis:

# Find authorization logic
grep -r "RBAC\|permissions\|roles\|authorize" {codebase_path}/src
grep -r "canAccess\|hasPermission\|checkRole" {codebase_path}/src

Security Measures Check:

# 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:

# 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:

# 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:

# 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:

# 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, in-memory, none)
• Code splitting (yes/no)
• Memoization usage (high, medium, low)
• Query optimization level (excellent, good, fair, poor)
• Performance score (0-100)

Performance Quality Indicators:

• Excellent (80-100): Optimized indexes, caching, code splitting, memoization
• Good (60-79): Some optimization, basic caching, indexes present
• Fair (40-59): Minimal optimization, missing key optimizations
• Poor (0-39): No optimization, performance bottlenecks likely

10. Assess Scalability

Action: Evaluate horizontal and vertical scaling capabilities

Horizontal Scaling Readiness:

• Stateless API design: +30 points
• Distributed caching (Redis): +20 points
• Database connection pooling: +15 points
• Load balancer ready: +10 points
• Background job processing: +15 points
• No server-side sessions: +10 points

Vertical Scaling Concerns:

• Single database instance: -20 points
• No read replicas: -15 points
• Synchronous processing: -10 points
• No queue system: -15 points

Scalability Checks:

# Check for stateless design
grep -r "session\|cookie-session" {codebase_path}/src

# Check for background jobs
grep -r "bull\|inngest\|agenda" {codebase_path}/src

# Check for distributed caching
grep -r "redis\|memcached" {codebase_path}/src

Output:

• Horizontal scaling readiness (0-100)
• Bottlenecks identified
• Scaling recommendations
• Current limitations

Scalability Quality Indicators:

• Excellent (80-100): Stateless, distributed cache, job queue, load balancer ready
• Good (60-79): Mostly stateless, basic caching, some async processing
• Fair (40-59): Some stateful components, limited caching
• Poor (0-39): Stateful design, no distributed components, single points of failure

11. Identify Technical Debt

Action: Find type errors, deprecated patterns, missing tests, documentation gaps

Type Safety Analysis (TypeScript):

# Run TypeScript compiler
npx tsc --noEmit 2>&1 | grep "error TS" | wc -l

# Count errors by type
npx tsc --noEmit 2>&1 | grep "error TS" | awk '{print $2}' | sort | uniq -c

Deprecated Patterns:

# Look for old patterns
grep -r "componentWillMount\|componentWillReceiveProps" {codebase_path}/src
grep -r "@ts-ignore\|@ts-expect-error" {codebase_path}/src | wc -l
grep -r "any" {codebase_path}/src | grep -v "node_modules" | wc -l

Missing Tests:

# Count test files
find {codebase_path}/src -name "*.test.*" -o -name "*.spec.*" | wc -l

# Count source files
find {codebase_path}/src -name "*.ts" -o -name "*.tsx" | grep -v ".test\|.spec" | wc -l

# Calculate rough coverage
# test_files / source_files * 100

Documentation Gaps:

# Check for documentation
find {codebase_path} -name "README.md" -o -name "*.md" | wc -l
find {codebase_path}/docs -name "*.md" 2>/dev/null | wc -l

Output:

• TypeScript error count
• Error breakdown by type
• Deprecated pattern count
• Test coverage estimate
• Documentation file count
• Technical debt priority list

Technical Debt Scoring:

• 0-100 errors: Low debt (90-100 points)
• 101-500 errors: Moderate debt (60-89 points)
• 501-1000 errors: High debt (30-59 points)
• 1000+ errors: Critical debt (0-29 points)

12. Review Testing Infrastructure

Action: Assess unit, integration, and E2E test coverage

Unit Tests:

# Find unit test files
find {codebase_path}/src -name "*.test.*" -o -name "*.spec.*" | wc -l
grep -r "describe\|it\|test(" {codebase_path}/src --include="*.test.*" | wc -l

Integration Tests:

# Look for integration test patterns
grep -r "supertest\|request(" {codebase_path}/src | wc -l
find {codebase_path} -path "*/tests/integration/*" -o -path "*/e2e/*"

E2E Tests:

# Check for E2E frameworks
find {codebase_path} -name "playwright.config.*" -o -name "cypress.config.*"
find {codebase_path} -path "*/e2e/*" -name "*.spec.*" | wc -l

Test Coverage:

# Check for coverage configuration
find {codebase_path} -name "vitest.config.*" -o -name "jest.config.*"
grep -r "coverage" {codebase_path}/package.json

Output:

• Unit test count
• Integration test count
• E2E test count
• Test framework (Vitest, Jest, Playwright, Cypress)
• Coverage tracking (yes/no)
• Testing score (0-100)

Testing Quality Indicators:

• Excellent (85-100): High coverage, all test types, automated CI
• Good (70-84): Unit + integration tests, some E2E, CI setup
• Fair (50-69): Basic unit tests, missing integration/E2E
• Poor (0-49): Minimal tests, no automation, no coverage tracking

13. Analyze External Integrations

Action: Identify third-party services and integration methods

Search for Integration Patterns:

# Look for API clients
grep -r "axios\|fetch\|got\|node-fetch" {codebase_path}/src
grep -r "prisma\|supabase\|firebase" {codebase_path}/src

# Look for SDKs
grep -r "@clerk\|@auth0\|stripe\|sendgrid\|twilio" {codebase_path}/package.json

Common Integrations to Check:

• Authentication: Clerk, Auth0, Firebase, Supabase
• Payments: Stripe, PayPal, Square
• Email: SendGrid, Mailgun, AWS SES
• SMS: Twilio, Vonage
• Storage: AWS S3, Cloudinary, Supabase Storage
• Analytics: Google Analytics, Mixpanel, Segment
• Monitoring: Sentry, Datadog, New Relic
• AI: OpenAI, Anthropic, Hugging Face
• Search: Algolia, Elasticsearch, Typesense
• Database: PostgreSQL, MongoDB, Redis

Integration Method:

• REST API
• SDK/Client Library
• Webhooks
• Event-driven
• Polling

Output:

• Service list with purpose
• Integration method per service
• SDK versions
• Webhook endpoints

14. Calculate Production Readiness Score

Action: Compute weighted score across all quality dimensions

Quality Dimensions & Weights:

Formula:

Production Readiness Score =
  (Architecture × 0.20) +
  (Code Quality × 0.15) +
  (Security × 0.15) +
  (Performance × 0.10) +
  (Scalability × 0.10) +
  (Maintainability × 0.15) +
  (Testing × 0.10) +
  (Monitoring × 0.05)

Score Interpretation:

• 90-100: ⭐⭐⭐⭐⭐ Excellent - Production Ready
• 80-89: ⭐⭐⭐⭐ Very Good - Minor improvements needed
• 70-79: ⭐⭐⭐⭐ Good - Moderate improvements needed
• 60-69: ⭐⭐⭐ Fair - Significant work required
• 50-59: ⭐⭐ Poor - Major rework needed
• 0-49: ⭐ Critical - Not production ready

Output: Overall production readiness score with breakdown

15. Generate Comprehensive Analysis Report

Action: Create detailed markdown report with all findings

Report Structure:

# {Project Name} - Architecture Analysis Report

## Executive Summary
- Project overview
- Overall assessment
- Production readiness score
- Key verdict

## 1. Architecture Overview
- Project structure
- Architecture pattern
- Key characteristics

## 2. Technology Stack
- Backend stack (with versions)
- Frontend stack (with versions)
- Database & infrastructure

## 3. Domain Model Analysis (if applicable)
- Domain entities
- Value objects
- Aggregates
- Domain events
- Application services
- CQRS handlers

## 4. CQRS Implementation (if applicable)
- Command side
- Query side
- Application services

## 5. Infrastructure Layer Analysis
- Database (schema stats)
- Real-time infrastructure
- Caching strategy
- Queue system

## 6. API Architecture
- REST API structure
- Middleware stack
- API versioning

## 7. Multi-Tenant Architecture (if applicable)
- Tenant isolation strategy
- Data isolation
- Security enforcement

## 8. Quality Assessment
- 8.1 Architecture Quality (score/100)
- 8.2 Code Quality (score/100)
- 8.3 Security (score/100)
- 8.4 Performance (score/100)
- 8.5 Scalability (score/100)
- 8.6 Maintainability (score/100)
- 8.7 Testing (score/100)
- 8.8 Monitoring (score/100)

## 9. Technical Debt Analysis
- Current technical debt items
- Priority breakdown (high/medium/low)
- Effort estimates

## 10. External Integrations
- Integration points table
- Integration methods

## 11. Key Recommendations
- 🔴 HIGH PRIORITY (with effort estimates)
- 🟡 MEDIUM PRIORITY (with effort estimates)
- 🟢 LOW PRIORITY (with effort estimates)

## 12. Risk Assessment
- Technical risks table
- Operational risks table

## 13. Production Readiness Checklist
- ✅ Already Complete (%)
- 🔧 Needs Completion (%)

## 14. Final Verdict
- Overall Score: X/100 ⭐⭐⭐⭐
- Category Breakdown (table)
- Success Probability

## 15. Conclusion
- Key achievements
- Critical path to production
- Bottom line recommendation

Output Formats:

Markdown (Default):

• Save to docs/architecture-analysis-{timestamp}.md
• Include emoji indicators (✅, ⚠️, ❌, 🔴, 🟡, 🟢)
• Tables for structured data
• Code blocks for examples

JSON (if requested):

{
  "timestamp": "2025-11-04T...",
  "project_name": "...",
  "project_type": "fullstack",
  "production_readiness_score": 85,
  "quality_scores": {
    "architecture": 95,
    "code_quality": 90,
    "security": 88,
    "performance": 78,
    "scalability": 82,
    "maintainability": 95,
    "testing": 85,
    "monitoring": 60
  },
  "architecture_patterns": ["DDD", "CQRS", "Layered"],
  "tech_stack": {...},
  "tech_debt": [...],
  "recommendations": [...],
  "risks": [...]
}

Success Criteria

An architecture analysis is complete when:

Analysis Coverage:

• ✅ Codebase structure discovered and documented
• ✅ Project type detected (frontend/backend/fullstack/monorepo)
• ✅ Architecture patterns identified (3+ if present)
• ✅ Technology stack documented with versions
• ✅ Domain model analyzed (if DDD/CQRS)
• ✅ API architecture assessed
• ✅ Security posture reviewed

Quality Assessment:

• ✅ Quality scores calculated for all 8 dimensions
• ✅ Production readiness score computed (0-100)
• ✅ Technical debt identified and prioritized
• ✅ Performance bottlenecks identified
• ✅ Scalability limitations documented

Recommendations:

• ✅ Recommendations provided (high/medium/low priority)
• ✅ Effort estimates included for each recommendation
• ✅ Risk assessment completed (technical + operational)
• ✅ Production readiness checklist generated

Report Quality:

• ✅ Comprehensive report generated (markdown and/or JSON)
• ✅ Report saved to docs/ directory
• ✅ Report includes all 15 sections
• ✅ Actionable insights provided

Example Usage

Example 1: Full Analysis (Current Directory)

User: /analyze-architecture

Winston: Analyzing architecture of current codebase...

[Discovers monorepo structure]
Project Type: Monorepo (backend + dashboard + chat-widget + shared packages)
Architecture: Pure 4-Layer DDD with CQRS

[Analyzes technology stack]
Backend: Node.js 20, TypeScript 5.8, Express 4.18, Prisma 6.9, PostgreSQL
Frontend: React 19, Material-UI 7.1, TanStack Query 5.81, Zustand 4.5

[Identifies patterns]
Patterns: Domain-Driven Design, CQRS, Layered Architecture, Event-Driven, Repository Pattern

[Calculates scores]
Architecture Quality: 95/100 ⭐⭐⭐⭐⭐
Code Quality: 90/100 ⭐⭐⭐⭐
Security: 88/100 ⭐⭐⭐⭐
Performance: 78/100 ⭐⭐⭐⭐
Scalability: 82/100 ⭐⭐⭐⭐
Maintainability: 95/100 ⭐⭐⭐⭐⭐
Testing: 85/100 ⭐⭐⭐⭐
Monitoring: 60/100 ⭐⭐⭐

Production Readiness Score: 85/100 ⭐⭐⭐⭐

✅ Report generated: docs/architecture-analysis-2025-11-04.md

Example 2: Focused Security Analysis

User: /analyze-architecture . --focus security

Winston: Analyzing security posture of codebase...

[Security analysis only]
✅ Authentication: Clerk-based JWT (Strong)
✅ Authorization: RBAC with permissions (Strong)
✅ Multi-tenant RLS: Row-level security enforced (Excellent)
✅ Input Validation: Zod schemas (Strong)
✅ SQL Injection: Protected by Prisma ORM (Strong)
✅ XSS Protection: React JSX escaping (Strong)
⚠️  Secrets: .env files (Needs secret manager)
⚠️  DDoS Protection: Basic rate limiting (Needs enhancement)
❌ Security Monitoring: No SIEM (Critical gap)

Security Score: 88/100 ⭐⭐⭐⭐

🔴 HIGH PRIORITY Recommendations:
1. Migrate secrets to AWS Secrets Manager or Vault
2. Implement comprehensive security monitoring (SIEM)
3. Add DDoS protection (Cloudflare, AWS Shield)

✅ Report generated: docs/security-analysis-2025-11-04.md

Example 3: JSON Output

User: /analyze-architecture . --output json

Winston: Analyzing architecture and generating JSON output...

✅ Analysis complete
✅ JSON report: docs/architecture-analysis-2025-11-04.json
✅ Markdown report: docs/architecture-analysis-2025-11-04.md

JSON output includes:
- production_readiness_score
- quality_scores (8 dimensions)
- architecture_patterns
- tech_stack
- tech_debt
- recommendations
- risks

Integration with Other Skills

Prerequisites:

• No formal architecture document required
• Works with brownfield codebases
• Discovers structure dynamically

Outputs used by:

• create-architecture: Use analysis to document existing architecture
• validate-architecture: Use findings to validate quality
• review-architecture: Use as input for peer review
• Implementation skills: Use recommendations to prioritize work

Workflow:

# Step 1: Analyze existing codebase
/analyze-architecture

# Step 2: Document architecture (if needed)
/design-architecture docs/prd.md --existing docs/architecture-analysis.md

# Step 3: Review and validate
/review-architecture docs/architecture.md

# Step 4: Implement recommendations
@james *implement <recommendation-from-analysis>

Telemetry

Track analysis metrics for continuous improvement:

{
  "skill": "analyze-architecture",
  "timestamp": "2025-11-04T...",
  "project_type": "monorepo",
  "architecture_patterns": ["DDD", "CQRS", "Layered"],
  "production_readiness_score": 85,
  "quality_scores": {
    "architecture": 95,
    "code_quality": 90,
    "security": 88,
    "performance": 78,
    "scalability": 82,
    "maintainability": 95,
    "testing": 85,
    "monitoring": 60
  },
  "tech_debt_count": 283,
  "recommendations_count": 10,
  "duration_ms": 180000,
  "focus_area": "all",
  "output_format": "markdown"
}

Quality Gates

Minimum Requirements for Complete Analysis:

• ✅ Codebase structure analyzed (directory tree, package.json files)
• ✅ Project type detected (with confidence score)
• ✅ Technology stack documented (with versions from package.json)
• ✅ At least 1 architectural pattern identified
• ✅ All 8 quality dimensions scored (0-100)
• ✅ Production readiness score calculated
• ✅ At least 3 recommendations provided
• ✅ Report generated in requested format

Escalation Triggers:

• Unable to detect project type (no package.json, no recognizable patterns)
• Zero architectural patterns identified
• Critical security vulnerabilities found (exposed secrets, SQL injection)
• Production readiness score < 50

References

• references/codebase-discovery-guide.md - Techniques for discovering structure
• references/architectural-patterns-catalog.md - Complete pattern reference
• references/tech-stack-catalog.md - Technology identification guide
• references/quality-scoring-rubrics.md - Scoring methodology for each dimension
• references/production-readiness-checklist.md - Complete checklist template

Analyze Architecture skill is ready to provide deep, comprehensive analysis of existing codebases. 🔍