Skip to main content Home Creators adolfoaranaes12 bmad-enhanced analyze-architecture
analyze-architecture 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.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/adolfoaranaes12/BMAD-ENHANCED --skill analyze-architectureThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... 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 judgingPattern recognition: Identify architectural patterns in useMulti-dimensional: Quality assessment across 8 key areasActionable insights: Prioritized recommendations with effort estimatesProduction focus: Calculate readiness for production deploymentBrownfield-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:
Discover Codebase Structure
Detect Project Type
Analyze Technology Stack
Identify Architectural Patterns
Calculate Quality Scores (simplified)
Identify Critical Technical Debt
Generate Quick Report
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
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:
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
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)
find {codebase_path}/docs -name "*architecture*.md" -mtime -30 2>/dev/null
find {codebase_path} -maxdepth 3 -type d | head -50
find {codebase_path} -name "package.json" -o -name "*.config.*" -o -name "tsconfig.json"
Monorepo detection: Multiple package.json files, workspaces configPackage structure: packages/, apps/, libs/, src/ directoriesConfiguration files: tsconfig.json, .eslintrc, vite.config.ts, etc.Documentation: README.md, docs/ folder, ARCHITECTURE.mdBuild artifacts: dist/, build/, node_modules/
Monorepo: Multiple packages with shared configurationStandalone: Single package with unified sourceMicroservices: Multiple independent servicesModular 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)
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)
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)
Next.js, Remix, SvelteKit, Nuxt
Both frontend and backend patterns present
API routes within same codebase
Shared types between client/server
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
find {codebase_path} -name "package.json" -not -path "*/node_modules/*" -exec cat {} \;
python .claude/skills/bmad-commands/scripts/extract_tech_stack.py \
--codebase {codebase_path} \
--output json
find {codebase_path} -name "schema.prisma" -exec cat {} \;
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)
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)
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):
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):
python .claude/skills/bmad-commands/scripts/validate_metrics.py \
--codebase {codebase_path}/src \
--metric cqrs \
--output json
{
"command_files" : 92 ,
"query_files" : 119 ,
"command_handlers" : 65 ,
"query_handlers" : 87 ,
"total_handlers" : 152 ,
"total_files" : 211
}
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"
find {codebase_path} -name "docker-compose.yml" -o -name "Dockerfile"
find {codebase_path}/services -type d -maxdepth 1
grep -r "EventEmitter" {codebase_path}/src
grep -r "EventBus" {codebase_path}/src
find {codebase_path}/src -path "*/events/*"
Hexagonal/Ports & Adapters:
find {codebase_path}/src -path "*/ports/*" -o -path "*/adapters/*"
grep -r "interface.*Port" {codebase_path}/src
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
find {codebase_path}/src -path "*/domain/entities/*" -o -path "*/entities/*"
grep -r "class.*Entity" {codebase_path}/src
find {codebase_path}/src -path "*/domain/value-objects/*" -o -path "*/value-objects/*"
grep -r "AggregateRoot" {codebase_path}/src
find {codebase_path}/src -path "*/domain/events/*" -o -path "*/events/*"
grep -r "DomainEvent" {codebase_path}/src
Discover Application 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 {codebase_path}/src -path "*/handlers/commands/*" -o -path "*/handlers/queries/*"
grep -r "CommandHandler\|QueryHandler" {codebase_path}/src | wc -l
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 logicGood: Entities present, some business logic in domainFair: Anemic domain model, logic in servicesPoor: No domain layer, data structures only
6. Assess API Architecture Action: Analyze API design, endpoints, and middleware
find {codebase_path}/src -path "*/routes/*" -o -path "*/controllers/*"
grep -r "router\." {codebase_path}/src | grep -E "(get|post|put|patch|delete)" | wc -l
REST: router.get(), router.post(), /api/v1/ patternsGraphQL: schema definitions, resolvers, apollo-servertRPC: .query(), .mutation(), typed proceduresgRPC: .proto files, protobuf definitions
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)
grep -r "/api/v[0-9]" {codebase_path}/src
API style (REST, GraphQL, tRPC, gRPC)
Endpoint count
Middleware stack
Versioning strategy
Authentication method
Authorization approach
Excellent: Versioned, validated, authenticated, documentedGood: Proper middleware, error handling, basic validationFair: Basic routes, some middleware missingPoor: No middleware, no validation, security gaps
7. Review Data Architecture Action: Analyze database schema, caching, and real-time infrastructure
find {codebase_path} -name "schema.prisma" -exec wc -l {} \;
find {codebase_path} -name "schema.prisma" -exec grep -E "model |enum " {} \; | wc -l
find {codebase_path} -path "*/prisma/migrations/*" -name "migration.sql" | wc -l
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)
grep -r "redis\|cache\|memcache" {codebase_path}/src --include="*.ts" | wc -l
find {codebase_path}/src -path "*/cache/*"
Identify Real-time Architecture:
grep -r "WebSocket\|SSE\|socket.io\|EventSource" {codebase_path}/src
find {codebase_path}/src -path "*/realtime/*"
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-timeGood: Proper schema, some indexes, basic cachingFair: Basic schema, missing indexes, no cachingPoor: Unoptimized schema, no indexes, performance issues
8. Analyze Security Posture Action: Assess authentication, authorization, and security measures
grep -r "passport\|jwt\|clerk\|auth0\|supabase" {codebase_path}/src
find {codebase_path}/src -path "*/auth/*"
grep -r "RBAC\|permissions\|roles\|authorize" {codebase_path}/src
grep -r "canAccess\|hasPermission\|checkRole" {codebase_path}/src
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
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
React (JSX escaping) = Protected
Helmet CSP headers = Protected
User input sanitization = Protected
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
grep -r "@@index\|@@id\|@@unique" {codebase_path}/prisma/schema.prisma | wc -l
grep -r "findMany\|findFirst" {codebase_path}/src | wc -l
grep -r "include:\|select:" {codebase_path}/src | wc -l
grep -r "redis.get\|cache.get" {codebase_path}/src | wc -l
grep -r "redis.set\|cache.set" {codebase_path}/src | wc -l
grep -r "React.lazy\|lazy(" {codebase_path}/src
grep -r "dynamic(.*import" {codebase_path}/src
grep -r "useMemo\|useCallback\|React.memo" {codebase_path}/src | wc -l
Proper indexes present: +20 points
Connection pooling configured: +10 points
Caching implemented: +20 points
Code splitting: +10 points
Memoization used: +10 points
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, memoizationGood (60-79): Some optimization, basic caching, indexes presentFair (40-59): Minimal optimization, missing key optimizationsPoor (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
grep -r "session\|cookie-session" {codebase_path}/src
grep -r "bull\|inngest\|agenda" {codebase_path}/src
grep -r "redis\|memcached" {codebase_path}/src
Horizontal scaling readiness (0-100)
Bottlenecks identified
Scaling recommendations
Current limitations
Scalability Quality Indicators:
Excellent (80-100): Stateless, distributed cache, job queue, load balancer readyGood (60-79): Mostly stateless, basic caching, some async processingFair (40-59): Some stateful components, limited cachingPoor (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):
npx tsc --noEmit 2>&1 | grep "error TS" | wc -l
npx tsc --noEmit 2>&1 | grep "error TS" | awk '{print $2}' | sort | uniq -c
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
find {codebase_path}/src -name "*.test.*" -o -name "*.spec.*" | wc -l
find {codebase_path}/src -name "*.ts" -o -name "*.tsx" | grep -v ".test\|.spec" | wc -l
find {codebase_path} -name "README.md" -o -name "*.md" | wc -l
find {codebase_path}/docs -name "*.md" 2>/dev/null | wc -l
TypeScript error count
Error breakdown by type
Deprecated pattern count
Test coverage estimate
Documentation file count
Technical debt priority list
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
find {codebase_path}/src -name "*.test.*" -o -name "*.spec.*" | wc -l
grep -r "describe\|it\|test(" {codebase_path}/src --include="*.test.*" | wc -l
grep -r "supertest\|request(" {codebase_path}/src | wc -l
find {codebase_path} -path "*/tests/integration/*" -o -path "*/e2e/*"
find {codebase_path} -name "playwright.config.*" -o -name "cypress.config.*"
find {codebase_path} -path "*/e2e/*" -name "*.spec.*" | wc -l
find {codebase_path} -name "vitest.config.*" -o -name "jest.config.*"
grep -r "coverage" {codebase_path}/package.json
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 CIGood (70-84): Unit + integration tests, some E2E, CI setupFair (50-69): Basic unit tests, missing integration/E2EPoor (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:
grep -r "axios\|fetch\|got\|node-fetch" {codebase_path}/src
grep -r "prisma\|supabase\|firebase" {codebase_path}/src
grep -r "@clerk\|@auth0\|stripe\|sendgrid\|twilio" {codebase_path}/package.json
Common Integrations to Check:
Authentication: Clerk, Auth0, Firebase, SupabasePayments: Stripe, PayPal, SquareEmail: SendGrid, Mailgun, AWS SESSMS: Twilio, VonageStorage: AWS S3, Cloudinary, Supabase StorageAnalytics: Google Analytics, Mixpanel, SegmentMonitoring: Sentry, Datadog, New RelicAI: OpenAI, Anthropic, Hugging FaceSearch: Algolia, Elasticsearch, TypesenseDatabase: PostgreSQL, MongoDB, Redis
REST API
SDK/Client Library
Webhooks
Event-driven
Polling
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:
Dimension Weight Score (0-100) Architecture 20% Calculated Code Quality 15% Calculated Security 15% Calculated Performance 10% Calculated Scalability 10% Calculated Maintainability 15% Calculated Testing 10% Calculated Monitoring 5% Calculated
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)
90-100: ⭐⭐⭐⭐⭐ Excellent - Production Ready80-89: ⭐⭐⭐⭐ Very Good - Minor improvements needed70-79: ⭐⭐⭐⭐ Good - Moderate improvements needed60-69: ⭐⭐⭐ Fair - Significant work required50-59: ⭐⭐ Poor - Major rework needed0-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
# {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
Save to docs/architecture-analysis-{timestamp}.md
Include emoji indicators (✅, ⚠️, ❌, 🔴, 🟡, 🟢)
Tables for structured data
Code blocks for examples
{
"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:
✅ 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 scores calculated for all 8 dimensions
✅ Production readiness score computed (0-100)
✅ Technical debt identified and prioritized
✅ Performance bottlenecks identified
✅ Scalability limitations documented
✅ Recommendations provided (high/medium/low priority)
✅ Effort estimates included for each recommendation
✅ Risk assessment completed (technical + operational)
✅ Production readiness checklist generated
✅ 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
No formal architecture document required
Works with brownfield codebases
Discovers structure dynamically
create-architecture: Use analysis to document existing architecturevalidate-architecture: Use findings to validate qualityreview-architecture: Use as input for peer reviewImplementation skills: Use recommendations to prioritize work
/analyze-architecture
/design-architecture docs/prd.md --existing docs/architecture-analysis.md
/review-architecture docs/architecture.md
@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
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 structurereferences/architectural-patterns-catalog.md - Complete pattern referencereferences/tech-stack-catalog.md - Technology identification guidereferences/quality-scoring-rubrics.md - Scoring methodology for each dimensionreferences/production-readiness-checklist.md - Complete checklist template
Analyze Architecture skill is ready to provide deep, comprehensive analysis of existing codebases. 🔍
More from this repository
Related occupations SOC
Based on SOC occupation classification
