Architecture Evaluation Framework

Purpose

"How sound is the architecture?" - This Skill provides comprehensive architectural analysis and evaluation capabilities for assessing system architecture quality, identifying architectural issues, and ensuring long-term maintainability and scalability.

Quick Start Example

Evaluate a Python project's architecture in 3 steps:

# 1. Run SOLID principles analysis
python solid_analyzer.py src/ -o reports/solid.md

# 2. Analyze coupling and cohesion
python coupling_analyzer.py src/ -o reports/coupling.md

# 3. Generate C4 diagrams
python c4_generator.py --system "MyApp" --output docs/architecture/

See complete working examples in EXAMPLES.md.

Core Evaluation Methods

1. Architecture Pattern Analysis

• What: Identify architectural patterns (MVC, microservices, layered, event-driven)
• When: Understanding existing architecture, migration planning
• How: Pattern detection algorithms, dependency analysis
• Details: Pattern identification in PATTERNS.md

2. SOLID Principles Evaluation

• What: Check adherence to SOLID design principles
• When: Code reviews, refactoring planning, quality audits
• How: AST analysis, method counting, dependency checking
• Details: SOLID analyzer implementation

3. Coupling and Cohesion Metrics

• What: Measure module dependencies and internal cohesion
• When: Identifying refactoring candidates, reducing complexity
• How: Dependency graphs, LCOM metrics, instability calculations
• Details: Coupling/cohesion patterns

4. Quality Attribute Scenarios (ATAM)

• What: Evaluate architecture trade-offs between quality attributes
• When: Major architectural decisions, technology selection
• How: Scenario-based evaluation, trade-off matrices
• Details: ATAM methodology

5. C4 Model Documentation

• What: Create hierarchical architecture diagrams (Context, Container, Component, Code)
• When: Documenting architecture, onboarding, reviews
• How: PlantUML generation, structured diagramming
• Details: C4 model guide

6. Architecture Decision Records (ADRs)

• What: Document and track architectural decisions
• When: Making significant architectural choices
• How: Structured templates, decision tracking
• Details: ADR templates

Table of Contents

Core Files

• KNOWLEDGE.md - Architecture theory, frameworks, methodologies
• PATTERNS.md - Implementation patterns and algorithms
• EXAMPLES.md - Complete working code examples
• GOTCHAS.md - Common pitfalls and troubleshooting
• REFERENCE.md - API documentation and metrics catalog

Quick Navigation

By Task

• Evaluating existing architecture → Start with Pattern Analysis
• Planning microservices migration → See Microservices evaluation
• Measuring technical debt → Use Technical debt quantification
• Creating architecture docs → Follow C4 model guide
• Reviewing SOLID compliance → Run SOLID analyzer

By Technology

• Python → Python architecture analysis
• JavaScript/TypeScript → JS/TS patterns
• Java → Java architecture tools
• Go → Go analysis patterns

Common Gotchas (Top 3)

1. Analysis Paralysis - Over-analyzing without implementation

   • Solution: Timebox analysis to 2-4 hours, validate with prototypes
   • More details in GOTCHAS.md

2. Ignoring Conway's Law - Architecture doesn't match team structure

   • Solution: Align team boundaries with architectural boundaries
   • See organizational patterns

3. Premature Optimization - Over-engineering for imagined scale

   • Solution: Design for current +1 order of magnitude only
   • Read scaling guidelines

Full list of gotchas in GOTCHAS.md.

Architecture Evaluation Process

1. Discovery & Documentation
   ├── Map current architecture
   ├── Identify components & boundaries
   └── Document data flows

2. Pattern Analysis
   ├── Identify architectural patterns
   └── Detect anti-patterns

3. Quality Attributes Assessment
   ├── Performance, Scalability, Security
   └── Reliability, Maintainability

4. Technical Analysis
   ├── SOLID compliance
   ├── Coupling & cohesion
   └── Dependency analysis

5. Risk & Debt Assessment
   ├── Identify risks
   └── Quantify technical debt

6. Recommendations & Roadmap
   ├── Prioritize improvements
   └── Create remediation plan

Best Practices

DO's

1. Document Architecture Early - Create diagrams before coding
2. Use Standard Models - Adopt C4, 4+1, or other frameworks
3. Capture Decisions - Write ADRs for significant choices
4. Measure Quality Attributes - Define metrics upfront
5. Automate Governance - Use fitness functions

DON'Ts

1. Don't Over-Engineer - Build for current +1 magnitude
2. Don't Ignore NFRs - Non-functional requirements matter
3. Don't Copy Blindly - Netflix architecture ≠ your startup
4. Don't Skip Documentation - Future you will thank you
5. Don't Work in Isolation - Involve stakeholders

Related Skills

• gap-analysis-framework - For identifying architectural gaps
• security-scanning-suite - For security architecture assessment
• evaluation-reporting-framework - For comprehensive reports
• codebase-onboarding-analyzer - For architecture understanding
• git-mastery-suite - For analyzing architectural evolution

Quick Reference

Key Commands

# Analyze SOLID compliance
python patterns/solid_analyzer.py src/

# Generate coupling report
python patterns/coupling_analyzer.py src/

# Create C4 diagrams
python patterns/c4_generator.py

# Generate ADR
python patterns/adr_manager.py new "Use Redis for caching"

# Run ATAM evaluation
python patterns/atam_evaluator.py

Essential Resources

• C4 Model - Architecture documentation
• ATAM Guide - Trade-off analysis
• ADR Repository - Decision records
• 12 Factor App - Modern app principles

See REFERENCE.md for complete API documentation and KNOWLEDGE.md for theoretical foundations.