architecture-evaluation-framework
Comprehensive architectural analysis and evaluation framework for system architecture assessment. Use for architecture pattern identification, SOLID principles evaluation, coupling/cohesion analysis, scalability assessment, performance characteristics, security architecture, data architecture, microservices vs monolith, technical debt quantification, and ADRs. Includes C4 model, 4+1 views, QAW, ATAM, architectural fitness functions, and visualization tools.
When & Why to Use This Skill
The Architecture Evaluation Framework is a comprehensive toolset designed for deep system architecture assessment and quality assurance. It empowers developers and architects to identify architectural patterns, evaluate adherence to SOLID principles, and analyze coupling and cohesion to ensure long-term maintainability. By leveraging industry-standard methodologies like the C4 model, ATAM, and ADR management, this skill helps quantify technical debt, assess scalability, and document critical architectural decisions effectively for robust software evolution.
Use Cases
- Legacy System Audit: Analyzing existing codebases to identify anti-patterns, quantify technical debt, and prioritize refactoring efforts based on structural metrics.
- Automated Architecture Documentation: Generating hierarchical C4 model diagrams and maintaining Architecture Decision Records (ADRs) to ensure documentation stays in sync with the code.
- Design Review & Validation: Evaluating system designs against quality attributes such as performance, security, and scalability using scenario-based ATAM evaluations.
- Microservices Migration Planning: Assessing component boundaries and dependency graphs to plan the transition from monolithic architectures to microservices.
- Continuous Governance: Implementing architectural fitness functions to automatically monitor and enforce design principles during the development lifecycle.
| name | architecture-evaluation-framework |
|---|---|
| description | Comprehensive architectural analysis and evaluation framework for system architecture assessment. Use for architecture pattern identification, SOLID principles evaluation, coupling/cohesion analysis, scalability assessment, performance characteristics, security architecture, data architecture, microservices vs monolith, technical debt quantification, and ADRs. Includes C4 model, 4+1 views, QAW, ATAM, architectural fitness functions, and visualization tools. |
| allowed-tools | [Read, Write, Edit, Bash, Glob, Grep, WebFetch] |
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)
Analysis Paralysis - Over-analyzing without implementation
- Solution: Timebox analysis to 2-4 hours, validate with prototypes
- More details in GOTCHAS.md
Ignoring Conway's Law - Architecture doesn't match team structure
- Solution: Align team boundaries with architectural boundaries
- See organizational patterns
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
- Document Architecture Early - Create diagrams before coding
- Use Standard Models - Adopt C4, 4+1, or other frameworks
- Capture Decisions - Write ADRs for significant choices
- Measure Quality Attributes - Define metrics upfront
- Automate Governance - Use fitness functions
DON'Ts
- Don't Over-Engineer - Build for current +1 magnitude
- Don't Ignore NFRs - Non-functional requirements matter
- Don't Copy Blindly - Netflix architecture ≠ your startup
- Don't Skip Documentation - Future you will thank you
- Don't Work in Isolation - Involve stakeholders
Related Skills
gap-analysis-framework- For identifying architectural gapssecurity-scanning-suite- For security architecture assessmentevaluation-reporting-framework- For comprehensive reportscodebase-onboarding-analyzer- For architecture understandinggit-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.