eyadsibai 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:
- Build import graph from source files
- Perform cycle detection (DFS)
- Report circular chains
- 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
- Map structure: Understand directory layout
- Identify entry points: Find main execution paths
- Build dependency graph: Map internal/external deps
- Detect issues: Circular deps, high coupling
- Recognize patterns: Identify design patterns used
- Evaluate quality: Check SOLID, coupling/cohesion
- Report findings: Summarize with recommendations
Quick Architecture Check
For rapid assessment:
- Review key configuration files
- Check import structure of main modules
- Identify obvious architectural issues
- 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
- Circular dependencies: Break cycles immediately
- God classes: Split into focused components
- Missing abstraction layers: Add interfaces
Medium Priority
- High coupling: Introduce dependency injection
- Inconsistent patterns: Standardize approaches
- Mixed responsibilities: Refactor to single responsibility
Low Priority
- Naming inconsistencies: Standardize naming
- Missing documentation: Add architecture docs
- 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