Review Architecture

This skill provides a systematic approach to reviewing code for architectural compliance with Beluga AI patterns and principles.

Prerequisites

• Code or design to review
• Understanding of target functionality
• Access to relevant packages

Review Process

1. Identify Scope

Determine what’s being reviewed:

• New package
• New provider
• Feature addition
• Refactoring
• Bug fix

2. Layer Compliance Check

Verify dependencies follow the architecture:

Application Layer (examples/)
       ↓
Agent Layer (pkg/agents/, pkg/orchestration/)
       ↓
LLM Layer (pkg/llms/, pkg/chatmodels/)
       ↓
RAG Layer (pkg/retrievers/, pkg/vectorstores/, pkg/embeddings/)
       ↓
Memory Layer (pkg/memory/)
       ↓
Infrastructure Layer (pkg/core/, pkg/config/, pkg/monitoring/, pkg/schema/)

Check for violations:

# Look for upward dependencies
grep -r "import.*pkg/agents" pkg/llms/       # Should be empty
grep -r "import.*pkg/llms" pkg/schema/       # Should be empty

3. Interface Segregation (ISP) Check

Red Flags:

// BAD: Too many methods
type Store interface {
    Get()
    Set()
    Delete()
    List()
    Watch()
    Backup()
    Restore()
    Compact()
    // ... more
}

4. Dependency Inversion (DIP) Check

Red Flags:

// BAD: Concrete dependency
type Agent struct {
    client *openai.Client  // Should be interface
}

// BAD: Global state
var defaultClient *http.Client

5. Single Responsibility (SRP) Check

Red Flags:

• Package name ends in “utils” or “helpers”
• Type has both business logic and I/O
• Method longer than 50 lines

6. Package Structure Check

Required files for each package:

7. Configuration Check

8. Error Handling Check

9. Observability Check

10. Provider Pattern Check (Multi-Provider Packages)

Review Output Template

## Architecture Review: [Component/PR Name]

### Summary
[Overall assessment: APPROVED / NEEDS CHANGES / REJECTED]

### Compliance Matrix

| Principle | Status | Notes |
|-----------|--------|-------|
| Layer Compliance | ✅/❌ | |
| ISP | ✅/❌ | |
| DIP | ✅/❌ | |
| SRP | ✅/❌ | |
| Package Structure | ✅/❌ | |
| Configuration | ✅/❌ | |
| Error Handling | ✅/❌ | |
| Observability | ✅/❌ | |

### Issues Found

#### Critical
1. [Issue]: [Location] - [Fix required]

#### Major
1. [Issue]: [Location] - [Recommendation]

#### Minor
1. [Issue]: [Location] - [Suggestion]

### Recommendations
1. [Specific recommendation]

### Positive Highlights
- [Good pattern usage]

Severity Definitions

Quick Reference: Anti-Patterns

1. Circular Dependencies: A imports B imports A
2. God Objects: Single type with many responsibilities
3. Service Locator: Runtime dependency lookup
4. Leaky Abstractions: Implementation details in interfaces
5. Global State: Mutable package-level variables
6. Deep Inheritance: Use composition instead
7. Missing Observability: No metrics or tracing

Output

A comprehensive review document with:

• Compliance assessment
• Issues categorized by severity
• Specific fix recommendations
• Positive pattern highlights