name: architecture-assessment description: Evaluates codebase architecture for patterns, anti-patterns, coupling, cohesion, scalability, and technical debt. Use when assessing system design, reviewing architecture decisions, identifying improvement areas, or preparing for major refactoring.

Architecture Assessment

Systematic evaluation of codebase architecture including pattern recognition, anti-pattern detection, coupling/cohesion analysis, scalability review, and technical debt identification.

Quick Start

Full architecture assessment:

Perform a comprehensive architecture assessment of this codebase, identifying patterns, anti-patterns, and improvement opportunities.

Pattern identification:

Identify the architectural patterns used in this project and evaluate how well they're implemented.

Technical debt analysis:

Analyze this codebase for technical debt and prioritize items for remediation.

Capabilities

1. Architecture Evaluation

Assess overall codebase architecture through structured analysis.

Evaluation Framework

1. STRUCTURE ANALYSIS
   - Directory organization
   - Module boundaries
   - Dependency flow
   - Layer separation

2. DESIGN PRINCIPLES
   - SOLID adherence
   - DRY compliance
   - Separation of concerns
   - Single responsibility

3. QUALITY ATTRIBUTES
   - Maintainability
   - Testability
   - Extensibility
   - Reliability

4. RISK ASSESSMENT
   - Complexity hotspots
   - Coupling issues
   - Change propagation
   - Failure domains

Architecture Health Score

Dimension	Weight	Indicators
Modularity	25%	Clear boundaries, low coupling, high cohesion
Maintainability	25%	Complexity metrics, documentation, test coverage
Scalability	20%	Statelessness, horizontal scaling potential
Testability	15%	Dependency injection, isolation, mock-ability
Security	15%	Input validation, auth boundaries, data protection

Scoring rubric:

90-100: Excellent - Minor improvements only
70-89: Good - Some areas need attention
50-69: Fair - Significant improvements needed
Below 50: Poor - Major refactoring required

2. Pattern Recognition

Identify and evaluate architectural patterns in the codebase.

Pattern Detection Matrix

Pattern	Directory Indicators	Code Indicators
MVC	`models/`, `views/`, `controllers/`	Route handlers, template rendering
MVVM	`viewmodels/`, `views/`	Two-way binding, observable state
Clean Architecture	`domain/`, `application/`, `infrastructure/`	Dependency inversion, use cases
Hexagonal	`ports/`, `adapters/`	Interface-based boundaries
Microservices	Multiple `package.json`, Dockerfiles	Service-to-service communication
Event-Driven	`events/`, `handlers/`, `subscribers/`	Event bus, message queues
CQRS	`commands/`, `queries/`	Separate read/write models
Repository	`repositories/`	Data access abstraction

Pattern Evaluation Criteria

For each identified pattern, assess:

## Pattern: {Name}

### Implementation Quality
- [ ] Pattern applied consistently across codebase
- [ ] Clear boundaries between pattern components
- [ ] Dependencies flow in correct direction
- [ ] Abstractions used appropriately

### Deviations
- List specific violations or inconsistencies
- Note areas where pattern is partially implemented
- Identify technical debt from pattern drift

### Recommendations
- Specific actions to improve implementation
- Priority (High/Medium/Low)
- Estimated effort

See references/architecture-patterns.md for detailed pattern analysis.

3. Anti-Pattern Detection

Identify architectural anti-patterns that harm maintainability and scalability.

Critical Anti-Patterns

Anti-Pattern	Symptoms	Impact	Fix
God Class	1000+ lines, 20+ methods, knows everything	Untestable, change-resistant	Extract classes by responsibility
Spaghetti Code	No clear structure, tangled dependencies	Impossible to maintain	Introduce layers, extract modules
Big Ball of Mud	No architecture, everything coupled	Technical bankruptcy	Incremental strangler pattern
Distributed Monolith	Microservices with shared DB, sync calls	Worst of both worlds	True service boundaries
Anemic Domain	DTOs with no behavior, logic in services	Fragile, scattered logic	Rich domain models
Circular Dependencies	A depends on B, B depends on A	Cannot evolve independently	Dependency inversion

Detection Commands

# Circular dependency detection
npx madge --circular src/
pydeps --show-cycles src/

# God class detection (files > 500 lines)
find src -name "*.ts" -exec wc -l {} \; | awk '$1 > 500'

# Coupling analysis
npx dependency-cruiser --output-type dot src | dot -T svg > deps.svg

See references/anti-patterns.md for comprehensive anti-pattern catalog.

4. Coupling Analysis

Measure and evaluate coupling between modules.

Coupling Types (Worst to Best)

Content Coupling - Module modifies internal data of another
Common Coupling - Shared global state
Control Coupling - One module controls flow of another via flags
Stamp Coupling - Shared data structures with unused fields
Data Coupling - Only necessary data passed (ideal)
Message Coupling - Loosest, communication via messages only

Coupling Metrics

## Module Coupling Report

### Afferent Coupling (Ca) - Who depends on me?
| Module | Dependents | Risk Level |
|--------|------------|------------|
| core/utils | 45 | HIGH - Changes break many |
| auth/jwt | 12 | MEDIUM |
| ui/Button | 8 | LOW |

### Efferent Coupling (Ce) - Who do I depend on?
| Module | Dependencies | Risk Level |
|--------|--------------|------------|
| pages/Dashboard | 23 | HIGH - Fragile |
| services/order | 8 | MEDIUM |
| utils/format | 2 | LOW |

### Instability Index
I = Ce / (Ca + Ce)
- 0.0 = Maximally stable (many dependents, few dependencies)
- 1.0 = Maximally unstable (few dependents, many dependencies)

Coupling Reduction Strategies

Strategy	When to Use	Example
Dependency Injection	Control coupling	Pass dependencies via constructor
Interface Segregation	Stamp coupling	Create specific interfaces
Event Bus	Control coupling	Decouple via events
Facade	Multiple dependencies	Single entry point

See references/metrics.md for coupling metric calculations.

5. Cohesion Assessment

Evaluate how well modules focus on single responsibilities.

Cohesion Types (Best to Worst)

Functional - All elements contribute to single task (ideal)
Sequential - Output of one element is input to next
Communicational - Elements operate on same data
Procedural - Elements related by execution order
Temporal - Elements execute at same time
Logical - Elements related by category, not function
Coincidental - No meaningful relationship (worst)

LCOM4 Metric

Lack of Cohesion of Methods:

LCOM = 0: Perfect cohesion
LCOM = 1: Acceptable
LCOM > 1: Low cohesion, consider splitting

Calculation:

LCOM4 = Number of connected components in method-field graph
- Each method is a node
- Edge exists if two methods share a field
- LCOM4 = number of disconnected subgraphs

Cohesion Assessment Template

## Cohesion Analysis: {ModuleName}

### Responsibility Inventory
1. {Responsibility 1}
2. {Responsibility 2}
...

### Cohesion Evaluation
- **Type**: {Functional|Sequential|etc.}
- **LCOM Score**: {0-N}
- **Field Usage Matrix**: Show which methods use which fields

### Recommendations
- [ ] Extract {Responsibility X} to new module
- [ ] Merge related methods
- [ ] Remove unrelated functionality

6. Scalability Review

Assess architecture for horizontal and vertical scaling capability.

Scalability Dimensions

Dimension	Assessment Questions
Statelessness	Can instances be added/removed freely? Is session state externalized?
Data Partitioning	Can data be sharded? Are there partition-limiting queries?
Async Processing	Are long-running tasks queued? Can work be distributed?
Caching Strategy	What's cached? Cache invalidation approach?
Database Access	Connection pooling? Read replicas? Query optimization?
Service Dependencies	Circuit breakers? Timeouts? Graceful degradation?

Scalability Anti-Patterns

Anti-Pattern	Impact	Detection	Fix
Sticky Sessions	Can't scale horizontally	Session affinity config	Externalize sessions (Redis)
Unbounded Queries	Memory exhaustion	`SELECT *` without LIMIT	Pagination, streaming
Sync Blocking Calls	Throughput bottleneck	Long-running HTTP calls	Async, message queues
Single Write Master	Write bottleneck	All writes to one DB	Sharding, CQRS
Memory-Bound Caching	Node memory limits	In-process cache	Distributed cache

Scalability Checklist

See checklists/scalability-checklist.md for detailed assessment.

7. Technical Debt Identification

Find, categorize, and prioritize technical debt.

Debt Categories

Category	Examples	Detection
Architecture Debt	Monolith needing split, wrong pattern	Architecture review
Code Debt	Complex functions, duplicates, dead code	Static analysis
Dependency Debt	Outdated packages, security vulns	`npm audit`, `pip-audit`
Test Debt	Low coverage, missing tests	Coverage reports
Documentation Debt	Outdated docs, missing API docs	Doc freshness check
Infrastructure Debt	Manual deployments, no IaC	Infrastructure review

Debt Prioritization Matrix

              Impact
         Low    |    High
        +-------+--------+
High    | PLAN  | DO NOW |
Effort  +-------+--------+
Low     | DEFER | DO SOON|
        +-------+--------+

Debt Inventory Template

## Technical Debt Inventory

### Critical (Fix within 2 weeks)
| ID | Description | Category | Impact | Effort | Owner |
|----|-------------|----------|--------|--------|-------|
| TD-001 | Security vulnerabilities in auth | Security | Critical | 2d | @dev |

### High (Fix within quarter)
| ID | Description | Category | Impact | Effort | Owner |
|----|-------------|----------|--------|--------|-------|
| TD-002 | Circular dependency in core | Architecture | High | 1w | @team |

### Medium (Track and address opportunistically)
...

### Low (Accept or defer)
...

See checklists/debt-assessment-checklist.md for systematic debt discovery.

Assessment Workflows

Full Architecture Assessment

1. DISCOVERY (1-2 hours)
   [ ] Clone/access repository
   [ ] Review documentation (README, ADRs, wiki)
   [ ] Interview stakeholders on pain points
   [ ] Identify key business domains

2. STATIC ANALYSIS (2-4 hours)
   [ ] Run complexity analysis (lizard, escomplex)
   [ ] Run dependency analysis (madge, pydeps)
   [ ] Check test coverage
   [ ] Audit dependencies

3. PATTERN ANALYSIS (1-2 hours)
   [ ] Identify primary architecture pattern
   [ ] Evaluate pattern adherence
   [ ] Document deviations

4. COUPLING/COHESION (1-2 hours)
   [ ] Map module dependencies
   [ ] Calculate coupling metrics
   [ ] Assess module cohesion

5. ANTI-PATTERN SCAN (1-2 hours)
   [ ] Check for god classes
   [ ] Find circular dependencies
   [ ] Identify distributed monolith signs

6. SCALABILITY REVIEW (1-2 hours)
   [ ] Assess statelessness
   [ ] Review data access patterns
   [ ] Check async processing

7. DEBT INVENTORY (2-4 hours)
   [ ] Catalog all debt
   [ ] Prioritize by impact/effort
   [ ] Estimate remediation costs

8. REPORT & RECOMMENDATIONS (2-4 hours)
   [ ] Compile findings
   [ ] Prioritize recommendations
   [ ] Create roadmap

Quick Health Check (30 min)

1. Structure scan - directory layout, layers
2. Complexity hotspots - top 5 complex files
3. Dependency health - vulnerabilities, outdated
4. Test coverage - overall percentage
5. Quick recommendations - top 3 issues

Output Templates