AI Assisted Architecture Analysis
Availability
✅
❌
From
October 25
Not Available
The AI-powered review functionality provides intelligent architecture and code quality analysis during pull request reviews. This feature automatically analyzes changed files using advanced language models to provide contextual insights about architectural patterns, Flxbl framework compliance, and potential improvements.
Overview
The architecture analysis performs real-time analysis of pull request changes to:
Analyze architectural patterns and design consistency
Identify alignment with Flxbl framework best practices
Suggest improvements based on changed files context
Provide severity-based insights (info, warning, concern)
Generate actionable recommendations
How It Works
The AI assisted architecture analyzer integrates into the project:analyze
command and:
Detects PR Context: Automatically identifies when running in a pull request environment
Analyzes Changed Files: Focuses analysis on modified files only (up to 10 files for token optimization)
Applies AI Analysis: Uses configured AI provider to analyze architectural patterns
Reports Findings: Generates structured insights without failing the build (informational only)
Creates GitHub Checks: Posts results as GitHub check annotations when running in CI
Prerequisites
OpenCode is currently only supported on OSX or Linux runtimes. It's not supported for Windows platforms.
For complete setup instructions, see Configuring LLM Providers.
Quick Setup:
# Install OpenCode CLI
npm install -g opencode-ai
nfigure Anthropic (recommended)
sfp ai auth --provider anthropic --auth
Configuration
The architecture analyzer is configured through a YAML configuration file at config/ai-architecture.yaml
:
# Enable/disable AI architecture analysis
enabled: true
# AI Provider Configuration (optional - auto-detects if not specified)
provider: anthropic # Options: anthropic, openai, google
model: claude-4-sonnet-xxxxx # Optional - uses provider defaults if not specified
# Architectural Patterns to Check
patterns:
- singleton
- factory
- repository
- service-layer
# Architecture Principles
principles:
- separation-of-concerns
- single-responsibility
- dependency-inversion
# Focus Areas for Analysis
focusAreas:
- security
- performance
- maintainability
- testability
# Additional Context Files (optional)
contextFiles:
- ARCHITECTURE.md
- docs/patterns.md
Minimal Configuration
For quick setup, create a minimal configuration:
enabled: true
The linter will auto-detect available AI providers and use sensible defaults.
AI Provider Setup
For detailed provider configuration, see Configuring LLM Providers.
Quick Reference
Anthropic (Recommended)
claude-4-sonnet-xxxxx
sfp ai auth --provider anthropic --auth
OpenAI
gpt-5
sfp ai auth --provider openai --auth
Amazon Bedrock
claude-4-sonnet-xxxxx
Configure AWS credentials
The linter auto-detects providers in this priority:
Environment variables (
ANTHROPIC_API_KEY
,OPENAI_API_KEY
, etc.)Stored credentials in
~/.sfp/ai-auth.json
Configuration in
ai-architecture.yaml
Usage in Pull Requests
Automatic PR Detection
When running in GitHub Actions or with PR environment variables:
# Automatically detects PR context and analyzes only changed files
sfp project:analyze
# Explicitly exclude AI linter if needed
sfp project:analyze --exclude-linters architecture
Manual Changed Files Specification
For local testing or custom CI environments:
# Manually specify changed files
sfp project:analyze --changed-files "src/classes/MyClass.cls,src/lwc/myComponent/myComponent.js"
Understanding Results
The AI linter provides structured insights without failing builds:
Insight Types
Pattern: Architectural patterns observed or missing
Concern: Potential issues requiring attention
Suggestion: Improvement recommendations
Alignment: Framework compliance observations
Severity Levels
Info: Informational observations
Warning: Areas needing attention
Concern: Significant architectural considerations
Sample Output
📐 Architecture Analysis Results
════════════════════════════════
✅ Analysis Complete (AI-powered by anthropic/claude-4-sonnet)
## Summary
Analyzed 5 changed files focusing on architectural patterns and Flxbl compliance.
## Key Insights
### ⚠️ Service Layer Pattern (Warning)
File: src/classes/AccountController.cls
Description: Direct SOQL queries in controller violates service layer pattern.
Consider moving data access logic to a dedicated service class.
### ℹ️ Dependency Management (Info)
File: src/classes/OrderService.cls
Description: Good use of dependency injection pattern for testability.
This aligns well with Flxbl framework principles.
### ⚠️ Error Handling (Concern)
File: src/classes/PaymentProcessor.cls:45
Description: Missing comprehensive error handling for external callouts.
Implement try-catch blocks with proper logging and user feedback.
## Recommendations
1. Extract data access logic to service layer classes
2. Implement centralized error handling strategy
3. Consider adding unit tests for new service methods
4. Document architectural decisions in ARCHITECTURE.md
Integration with CI/CD
GitHub Actions Integration
- name: Run Project Analysis with AI Linter
run: |
sfp project:analyze --output-format github
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# GitHub context automatically detected
Handling Rate Limits
The linter gracefully handles API limitations:
Rate Limits: Skips analysis with informational message
Timeouts: 60-second timeout protection
Token Limits: Analyzes up to 10 files, content limited to 5KB per file
Failures: Never blocks PR merge (informational only)
Best Practices
1. Configure Focus Areas
Tailor analysis to your team's priorities:
focusAreas:
- security # For compliance-critical projects
- performance # For high-volume applications
- maintainability # For long-term projects
2. Add Context Files
Provide architectural documentation for better analysis:
contextFiles:
- ARCHITECTURE.md
- docs/coding-standards.md
- docs/patterns.md
3. Use with Other Linters
Combine with other analysis tools for comprehensive coverage:
# Run all linters including AI analysis
sfp project:analyze --fail-on duplicates,compliance
# AI linter provides insights, others enforce rules
4. Token Optimization
For large PRs, the linter automatically:
Limits to 10 most relevant files
Truncates file content to 5KB
Focuses on text-based source files
Troubleshooting
AI Provider Not Detected
# Check available providers
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
# Or use authenticated provider
sfp ai auth --provider anthropic --auth
Analysis Skipped
Common reasons and solutions:
Not Enabled: Set
enabled: true
inconfig/ai-architecture.yaml
No Provider: Configure API keys or authenticate with
sfp ai auth
Rate Limited: Wait for rate limit reset or use different provider
No Changed Files: Ensure PR context is properly detected
Debugging
Enable debug logging for detailed information:
sfp project:analyze --loglevel debug
This shows:
Provider detection process
Changed files identified
API calls and responses
Error details if analysis fails
Limitations
Binary Files: Skips non-text files
Build Impact: Never fails builds (informational only)
Language Support: Best for Apex, JavaScript, TypeScript, XML
See Also
AI Assisted Insight Report - For comprehensive project analysis
Compliance Check - For rule-based enforcement
Duplicate Check - For identifying duplicate components
Last updated