Docs
flxbl.ioStatusContact us
codevsfp CLIsfp serverlibraries

AI Assisted Architecture Analysis

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:

  1. Detects PR Context: Automatically identifies when running in a pull request environment
  2. Analyzes Changed Files: Focuses analysis on modified files only (up to 10 files for token optimization)
  3. Applies AI Analysis: Uses configured AI provider to analyze architectural patterns
  4. Reports Findings: Generates structured insights without failing the build (informational only)
  5. Creates GitHub Checks: Posts results as GitHub check annotations when running in CI

Prerequisites

For complete setup instructions, see Configuring LLM Providers.

Configuration

The architecture analyzer is configured through a YAML configuration file. The file is checked in this order:

  1. config/ai-assist.yaml — preferred name for new projects
  2. config/ai-architecture.yaml — legacy name, still fully supported
# config/ai-assist.yaml
# (also accepted as config/ai-architecture.yaml for legacy projects)

enabled: true

# AI provider to use. Auto-detected from environment variables if omitted.
# Valid values: anthropic, openai, google, amazon-bedrock, github-copilot
provider: anthropic

# Optional: specific model to use. Defaults to the provider's recommended model.
model: claude-sonnet-4-5

# Timeout in milliseconds. Minimum 600000 (10 minutes) recommended.
timeout: 600000

# Salesforce/FLXBL architectural patterns the AI should recognise and evaluate.
patterns:
  - "Service Layer Pattern"
  - "Repository Pattern"
  - "Trigger Handler Pattern"
  - "Selector Pattern"
  - "Domain Layer Pattern"
  - "Unit of Work Pattern"

# Guiding principles the AI should use when assessing the changes.
principles:
  - "Separation of Concerns"
  - "Single Responsibility Principle"
  - "Bulkification of DML and SOQL"
  - "Security (CRUD/FLS enforcement)"
  - "Governor Limit Awareness"

# Aspects of the code the AI should focus its analysis on.
focusAreas:
  - "Error Handling and Logging"
  - "Governor Limits"
  - "Test Coverage and Quality"
  - "Security and Sharing Model"
  - "Trigger Best Practices"

# Additional repository files to include as context for the AI.
# Paths are relative to the repository root.
contextFiles:
  - "docs/architecture.md"
  - "docs/patterns.md"
  - "README.md"

# Change significance thresholds (see below).
changeSignificance:
  excludedMetadataTypes:
    - "CustomLabel"
    - "Translation"
    - "StaticResource"
  fileTypeThresholds:
    apex:
      lines: 50
      files: 3
    flows:
      lines: 100
      files: 2
    lwc:
      lines: 80
      files: 3
    default:
      lines: 200
      files: 5
  ignoredFilePatterns:
    - "**/*.md"
    - "**/test/**"
    - "**/__tests__/**"

Minimal Configuration

For quick setup, create a minimal configuration:

enabled: true

The linter will auto-detect available AI providers and use sensible defaults.

Configuration Field Reference

FieldTypeDefaultDescription
enabledbooleantrueWhether the architecture linter is active (still gated by analyze.yaml).
providerstringauto-detectAI provider to use.
modelstringprovider defaultSpecific model to use.
timeoutnumber600000Milliseconds before the AI call is abandoned.
patternsstring[][]Architectural pattern names for the AI to recognize.
principlesstring[][]Guiding principles for the AI's evaluation.
focusAreasstring[][]Specific areas of concern for the AI to focus on.
contextFilesstring[][]Repository files to include as context in the AI prompt.
changeSignificanceobject—Thresholds for skipping trivial PRs.
changeSignificance.excludedMetadataTypesstring[][]Metadata types never considered significant.
changeSignificance.fileTypeThresholdsobject—Per-type lines/files thresholds.
changeSignificance.ignoredFilePatternsstring[][]Glob patterns for files excluded from significance calculation.

Change Significance Filtering

When changeSignificanceEnabled is set to true in config/analyze.yaml (or per branch rule), PRs below the configured thresholds are skipped — no AI call is made. This saves API costs for trivial changes.

A PR is considered "significant" if it meets either the lines or files threshold for any file type. Metadata types listed in excludedMetadataTypes are never considered significant, and files matching ignoredFilePatterns are excluded from the calculation.

# config/ai-assist.yaml
changeSignificance:
  excludedMetadataTypes:
    - "CustomLabel"
    - "Translation"
    - "StaticResource"
  fileTypeThresholds:
    apex:
      lines: 50      # Changed lines of Apex
      files: 3       # Number of Apex files changed
    flows:
      lines: 100
      files: 2
    lwc:
      lines: 80
      files: 3
    default:
      lines: 200     # Fallback for any other file type
      files: 5
  ignoredFilePatterns:
    - "**/*.md"
    - "**/test/**"
    - "**/__tests__/**"

AI Provider Setup

For detailed provider configuration, see Configuring LLM Providers.

Quick Reference

ProviderEnvironment VariableSetup
Anthropic (Recommended)ANTHROPIC_API_KEYexport ANTHROPIC_API_KEY="sk-ant-xxx"
OpenAIOPENAI_API_KEYexport OPENAI_API_KEY="sk-xxx"
GoogleGOOGLE_API_KEY or GOOGLE_GENERATIVE_AI_API_KEYexport GOOGLE_API_KEY="xxx"
Amazon BedrockAWS credentials in environmentexport AWS_BEARER_TOKEN_BEDROCK + AWS_REGION
GitHub CopilotGitHub token (auto-detected in CI)export COPILOT_TOKEN="ghu_xxx"

The linter auto-detects providers in this priority:

  1. Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, etc.)
  2. Configuration in ai-assist.yaml (or 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-sonnet-4-5-20250929)

## 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

AI linter results are informational only and never fail the build. This ensures PR checks remain stable even if AI providers are unavailable.

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

Analysis Skipped

Common reasons and solutions:

  1. Not Enabled: Set enabled: true in config/ai-assist.yaml (or config/ai-architecture.yaml)
  2. No Provider: Configure API keys via environment variables (see Configuring LLM Providers)
  3. Rate Limited: Wait for rate limit reset or use different provider
  4. 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

  1. Binary Files: Skips non-text files
  2. Build Impact: Never fails builds (informational only)
  3. Language Support: Best for Apex, JavaScript, TypeScript, XML

AI Assisted Insight Report

Previous Page

AI Assisted Version Intent

An opt-in analyze addon that reads a pull request diff and applies a semantic version intent by posting a /version comment authored by the app.

On this page

OverviewHow It WorksPrerequisitesConfigurationMinimal ConfigurationConfiguration Field ReferenceChange Significance FilteringAI Provider SetupQuick ReferenceUsage in Pull RequestsAutomatic PR DetectionManual Changed Files SpecificationUnderstanding ResultsInsight TypesSeverity LevelsSample OutputIntegration with CI/CDGitHub Actions IntegrationHandling Rate LimitsBest Practices1. Configure Focus Areas2. Add Context Files3. Use with Other Linters4. Token OptimizationTroubleshootingAnalysis SkippedDebuggingLimitations