Stop guessing about architecture decisions. Get AI-powered recommendations for your actual code.
The AI Architecture Advisor analyzes your codebase and provides expert recommendations on design patterns, architectural decisions, and refactoring opportunities. Powered by sequential thinking AI and trained on comprehensive pattern knowledge.
- 🧠 Analyzes your actual code - Not just theory, real analysis of your projects
- 🎯 Recommends specific patterns - With confidence levels and reasoning
- 🛡️ Prevents anti-patterns - Catches overengineering before it happens
- 🔍 Finds refactoring opportunities - Identifies code that would benefit from patterns
- 📊 Provides implementation guidance - Step-by-step pattern application
Prerequisites: Claude Code CLI installed
# 1. Clone and setup
git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
cd ai-architecture-advisor
./setup.sh # Installs commands globally
# 2. Use from ANY directory - no need to stay in ai-architecture-advisor!
cd /path/to/your/project
claude .
# 3. Start getting AI recommendations
/dp::analyze Your architectural challenge description here
# 4. Analyze your existing code
/dp::refactor main.py
# 5. Validate pattern decisions
/dp::check singleton for database connection pool→ Full Quick Start Guide ← Start here!
For complex architectural decisions
/dp::analyze Payment system with multiple providers, different validation rules, and varying processing timesGet 8-step AI analysis with pattern recommendations, alternatives, and implementation roadmap
For specific pattern decisions
/dp::check factory for creating different database connectionsFast ✅/❌ validation with clear reasoning
For existing code improvement
/dp::refactor /path/to/your/codebase/Identifies pattern opportunities with priority scores
For avoiding architectural mistakes
/dp::validate Making all service classes singletons for consistencyPrevents overengineering and common mistakes
❌ Generic advice and theoretical examples
❌ "Here's how to implement X pattern"
❌ No analysis of your specific code
❌ No guidance on when NOT to use patterns
✅ Analyzes YOUR specific code and problems
✅ Tells you WHEN to use patterns (and when not to)
✅ Prevents anti-patterns and overengineering
✅ Provides confidence levels and reasoning
✅ Sequential thinking for complex decisions
Your Problem:
/dp::analyze E-commerce platform with user auth, product catalog, shopping cart, order processing, payment handling, inventory management. Team of 8 developers.AI Analysis:
🧠 Pattern Analysis: E-commerce Platform Architecture
## Problem Assessment
- Complexity: High (6+ domains, team coordination)
- Scale: Multi-domain system requiring modularity
- Growth Potential: High (e-commerce evolves rapidly)
## Primary Recommendations:
### 1. Repository Pattern (Confidence: HIGH)
✓ 6+ data domains justify separate repositories
✓ Team of 8 needs independent development paths
✓ Testing isolation critical for this complexity
### 2. Strategy Pattern for Payments (Confidence: HIGH)
✓ Multiple payment methods with different logic
✓ Runtime selection based on user/region
✓ Expected growth (crypto, BNPL, etc.)
### 3. Observer Pattern for Order Events (Confidence: MEDIUM)
✓ Inventory updates, notifications, analytics
✓ Decoupled event handling across domains
## Anti-Pattern Warnings:
🚨 Avoid generic repository (IRepository<T>)
🚨 Don't make everything singleton
⚠️ Watch for god objects in order processing
## Implementation Priority:
1. Repository pattern (foundational)
2. Payment strategies (business critical)
3. Event system (quality improvement)
[... detailed implementation steps ...]
ai-architecture-advisor/
├── 📋 README.md # You are here
├── ⚡ QUICK_START.md # Get started in 5 minutes
├── 🤖 commands/ # Primary AI interface
│ ├── analyze.md # Deep architectural analysis
│ ├── check.md # Quick pattern validation
│ ├── refactor.md # Code improvement analysis
│ └── validate.md # Anti-pattern prevention
├── 🧠 ai-engine/ # Intelligence core
│ ├── pattern_knowledge.py # Comprehensive pattern database
│ ├── code_analyzer.py # AST-based code analysis
│ ├── repo_analyzer.py # Repository-wide insights
│ └── refactoring_templates.py # Implementation guidance
├── 📚 learning-resources/ # Educational materials
│ ├── notebooks/ # Interactive pattern tutorials
│ ├── guides/ # Documentation and decision trees
│ └── examples/ # Implementation examples & tests
├── 🔧 .claude/ # AI command configuration
└── 📄 CLAUDE.md # AI assistant guidelines
For developers with real projects
- Start with
/dp::analyzeon your current architectural challenges - Use
/dp::refactorto improve existing code - Learn patterns through AI recommendations and targeted study
- Validate understanding with
/dp::check
For systematic pattern education
- Study interactive notebooks in
learning-resources/notebooks/ - Practice with implementation examples
- Apply patterns to real projects
- Use AI commands to validate your decisions
The AI uses advanced sequential thinking to:
- Break down complex architectural problems into steps
- Consider multiple pattern options systematically
- Evaluate trade-offs and alternatives
- Provide reasoning for recommendations
- Extracted from 10 comprehensive pattern tutorials
- Threshold-based recommendations (e.g., Strategy for 3+ algorithms)
- Anti-pattern detection with specific warnings
- Context-aware analysis (team size, complexity, growth)
- AST-based Python code analysis
- Pattern opportunity detection
- Complexity metrics and thresholds
- Priority scoring for refactoring suggestions
- Python 3.11+ (optional, for notebooks)
- Claude Code CLI (required for dp:: commands)
# Clone the repository
git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
cd ai-architecture-advisor
# Run the setup script to enable dp:: commands
./setup.sh
# Or manually copy commands
mkdir -p .claude/commands
cp commands/*.md .claude/commands/# Open Claude Code
claude .
# Test a command
/dp::analyze I need a payment processing systemThat's it! The dp:: commands are now available in Claude Code.
→ Detailed Setup Guide for troubleshooting and manual setup.
- 4 Smart Commands for comprehensive architecture guidance
- Sequential Thinking for complex decision analysis
- Anti-Pattern Detection with risk assessment
- Code Analysis with refactoring recommendations
- Confidence Scoring for all recommendations
- 10 Design Patterns with interactive tutorials
- Real-world Examples and implementation guides
- Decision Trees and visual guides
- Comprehensive Test Suites with >90% coverage
Creational: Singleton, Factory, Builder
Structural: Adapter, Decorator
Behavioral: Observer, Strategy, Command, State
Architectural: Repository
We welcome contributions to improve the AI recommendations and expand pattern coverage!
- Pattern knowledge enhancement - Add more advanced scenarios
- Code analysis improvements - Better pattern detection algorithms
- New language support - Extend beyond Python
- AI prompt refinement - Improve recommendation quality
See CONTRIBUTING.md for guidelines.
MIT License - See LICENSE for details.
→ Quick Start Guide - Get recommendations in 5 minutes
→ Interactive Tutorials - Comprehensive pattern education
The AI Architecture Advisor helps teams make consistent, well-reasoned architectural decisions. No more endless debates about whether to use a pattern - get expert AI analysis instead.
🌟 If this helps you write better code, please give it a ⭐
Questions? Open an issue or check the documentation.
Stop wondering. Start knowing. 🚀