Architecture Review

Comprehensive architecture analysis skill for understanding project structure, dependencies, and design patterns.

Core Capabilities

Project Structure Analysis

Understand and evaluate codebase organization:

Directory Structure Patterns:

• Flat structure (small projects)
• Feature-based organization
• Layer-based organization (MVC, Clean Architecture)
• Domain-driven design structure

Key files to identify:

• Entry points (main.py, index.js, cmd/)
• Configuration files
• Test directories
• Build/deploy configurations
• Documentation

Structure assessment:

project/
├── src/          # Source code
├── tests/        # Test files
├── docs/         # Documentation
├── scripts/      # Utility scripts
├── config/       # Configuration
└── README.md     # Project overview

Dependency Analysis

Map and evaluate dependencies:

Internal Dependencies:

• Module import graphs
• Circular dependency detection
• Coupling analysis
• Cohesion measurement

External Dependencies:

• Third-party package analysis
• Version constraints
• Transitive dependencies
• License compatibility

Dependency visualization:

# Python - using pydeps
pydeps --cluster src/

# Python - using pipdeptree
pipdeptree --warn silence

# JavaScript
npm ls --all

Circular Import Detection

Identify and resolve circular dependencies:

Detection approach:

1. Build import graph from source files
2. Perform cycle detection (DFS)
3. Report circular chains
4. Suggest resolution strategies

Resolution strategies:

• Extract shared code to new module
• Use dependency injection
• Lazy imports (import inside function)
• Interface segregation

Design Pattern Recognition

Identify common patterns in code:

Creational Patterns:

• Factory (object creation abstraction)
• Singleton (single instance)
• Builder (step-by-step construction)
• Dependency Injection

Structural Patterns:

• Adapter (interface conversion)
• Decorator (dynamic behavior)
• Facade (simplified interface)
• Repository (data access abstraction)

Behavioral Patterns:

• Strategy (algorithm selection)
• Observer (event handling)
• Command (action encapsulation)
• State (state machine)

Architecture Evaluation

Layer Analysis

For layered architectures, verify:

Presentation Layer:

• Controllers/Views
• Input validation
• Response formatting

Business Layer:

• Domain logic
• Business rules
• Service orchestration

Data Layer:

• Repositories
• Data access
• External integrations

Cross-cutting concerns:

• Logging
• Authentication
• Error handling
• Caching

Coupling & Cohesion

Coupling (lower is better):

• Afferent coupling (Ca): Who depends on this module
• Efferent coupling (Ce): What this module depends on
• Instability: Ce / (Ca + Ce)

Cohesion (higher is better):

• Single responsibility adherence
• Related functionality grouping
• Clear module boundaries

SOLID Principles Check

Evaluate adherence to:

S - Single Responsibility:

• Each class has one reason to change
• Clear, focused modules

O - Open/Closed:

• Open for extension
• Closed for modification

L - Liskov Substitution:

• Subtypes substitutable for base types
• Proper inheritance hierarchies

I - Interface Segregation:

• Specific interfaces over general ones
• No forced implementation of unused methods

D - Dependency Inversion:

• Depend on abstractions
• High-level modules independent of low-level

Analysis Workflow

Full Architecture Review

1. Map structure: Understand directory layout
2. Identify entry points: Find main execution paths
3. Build dependency graph: Map internal/external deps
4. Detect issues: Circular deps, high coupling
5. Recognize patterns: Identify design patterns used
6. Evaluate quality: Check SOLID, coupling/cohesion
7. Report findings: Summarize with recommendations

Quick Architecture Check

For rapid assessment:

1. Review key configuration files
2. Check import structure of main modules
3. Identify obvious architectural issues
4. Note areas needing deeper review

Output Format

Structure Report

Project: my-project
Type: Web Application (FastAPI)
Architecture: Layered (API/Service/Repository)

Directory Structure:
├── api/          [Presentation Layer]
├── services/     [Business Layer]
├── repositories/ [Data Layer]
├── models/       [Domain Models]
└── utils/        [Shared Utilities]

Entry Points:
- main.py (FastAPI application)
- cli.py (Command line interface)

Dependency Report

Module Dependencies:
┌─────────────┬────────────┬────────────┐
│ Module      │ Imports    │ Imported By│
├─────────────┼────────────┼────────────┤
│ api.users   │ 5          │ 2          │
│ services.   │ 8          │ 4          │
│ repos.db    │ 3          │ 6          │
└─────────────┴────────────┴────────────┘

Circular Dependencies Found: 2
1. services.auth → services.user → services.auth
2. models.order → models.product → models.order

Quality Assessment

Aspect	Score	Notes
Structure	8/10	Clear layer separation
Coupling	6/10	Some tight coupling in services
Cohesion	7/10	Good module focus
SOLID	7/10	DI could be improved

Common Architectural Issues

High Priority

1. Circular dependencies: Break cycles immediately
2. God classes: Split into focused components
3. Missing abstraction layers: Add interfaces

Medium Priority

1. High coupling: Introduce dependency injection
2. Inconsistent patterns: Standardize approaches
3. Mixed responsibilities: Refactor to single responsibility

Low Priority

1. Naming inconsistencies: Standardize naming
2. Missing documentation: Add architecture docs
3. Test organization: Align with source structure

Recommendations Template

For each finding, provide:

Issue: [Description]
Location: [Files/modules affected]
Impact: [Why this matters]
Recommendation: [How to fix]
Effort: [Low/Medium/High]
Priority: [High/Medium/Low]

Integration

Coordinate with other skills:

• refactoring skill: For implementing architectural changes
• documentation skill: For architecture documentation
• code-quality skill: For detailed code analysis