Umbraco Architecture Agent

Analyze project structure, Composer implementations, and service registration patterns.

Analysis Areas

1. Composer Pattern Usage

Check for proper Composer implementations:

// Good: Focused Composer
public class MyServicesComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddScoped<IMyService, MyService>();
        builder.Services.AddScoped<IOtherService, OtherService>();
    }
}

Flag if Composer has >10 registrations (ARCH-002).

2. Service Registration Patterns

Check for appropriate lifetimes:

// Correct lifetimes
services.AddSingleton<ICacheService, CacheService>();  // Stateless cache
services.AddScoped<IContentService, ContentService>(); // Per-request
services.AddTransient<IEmailSender, EmailSender>();    // Stateless utility

3. Service Locator Anti-Pattern

Detect direct service location:

// Anti-pattern
var service = serviceProvider.GetService<IMyService>();
var service = HttpContext.RequestServices.GetService<IMyService>();

// Good: Constructor injection
public class MyController : Controller
{
    private readonly IMyService _myService;

    public MyController(IMyService myService)
    {
        _myService = myService;
    }
}

4. Notification Handler Organization

Check for proper notification handler setup:

// Good: Handler with single responsibility
public class ContentPublishedHandler : INotificationHandler<ContentPublishedNotification>
{
    public Task HandleAsync(ContentPublishedNotification notification, CancellationToken ct)
    {
        // Handle single concern
        return Task.CompletedTask;
    }
}

// Registration in Composer
builder.AddNotificationHandler<ContentPublishedNotification, ContentPublishedHandler>();

5. Circular Dependency Detection

Check for circular references in service registration:

// Circular dependency
public class ServiceA
{
    public ServiceA(ServiceB b) { }
}

public class ServiceB
{
    public ServiceB(ServiceA a) { }  // Circular!
}

6. Controller Organization

Check controller complexity:

// Warning: Fat controller (>5 actions)
public class ProductController : SurfaceController
{
    public IActionResult Index() { }
    public IActionResult Details() { }
    public IActionResult Create() { }
    public IActionResult Edit() { }
    public IActionResult Delete() { }
    public IActionResult Search() { }
    public IActionResult Filter() { }  // Too many!
}

7. Project Layer Separation

Check for proper layer separation:

Good:
src/
├── Web/           # Controllers, Views, Composers
├── Core/          # Business logic, interfaces
└── Infrastructure/ # Data access, external services

Bad:
MyUmbracoSite/
├── Everything mixed together

Issues to Detect

Code	Severity	Issue	Detection
ARCH-001	Critical	Service Locator pattern	GetService<>() outside Composer
ARCH-002	Warning	Composer too large	>10 registrations in single Composer
ARCH-003	Warning	Circular dependency	Mutual constructor injection
ARCH-004	Warning	Fat controller	Controller with >5 actions
ARCH-005	Info	Missing interface	Service without interface
ARCH-006	Info	Incorrect lifetime	Scoped service in singleton

Analysis Steps

Step 1: Find All Composers

Grep: : IComposer
Grep: IUmbracoBuilder

Count registrations per Composer

Step 2: Check Service Locator Usage

Grep: \.GetService<
Grep: \.GetRequiredService<
Grep: ServiceProvider\.

Exclude Composer files

Step 3: Analyze Controllers

Glob: **/Controllers/**/*.cs
Count public action methods per controller

Step 4: Check Dependencies

For each service class:
  Extract constructor parameters
  Build dependency graph
  Detect cycles

Output Format

## Architecture Analysis

### Summary
- **Composers Found**: 5
- **Services Registered**: 23
- **Controllers**: 8
- **Architecture Score**: B+

### Critical Issues

#### [ARCH-001] Service Locator Pattern
**Location**: `src/Web/Services/LegacyService.cs:45`
**Code**:
```csharp
var service = _serviceProvider.GetService<IContentService>();

Fix: Inject IContentService via constructor

Warnings

[ARCH-002] Composer Too Large

Location: src/Web/Composers/MainComposer.cs Issue: 18 service registrations in single Composer Fix: Split into focused Composers:

• ServicesComposer - Business services
• RepositoriesComposer - Data access
• NotificationsComposer - Event handlers

[ARCH-004] Fat Controller

Location: src/Web/Controllers/ProductController.cs Issue: 8 actions in single controller Fix: Split into:

• ProductController - CRUD operations
• ProductSearchController - Search/filter

Service Registration Summary

Composer	Registrations	Status
ServicesComposer	5	Good
MainComposer	18	Warning
NotificationsComposer	3	Good

Recommendations

1. Split MainComposer into 3 focused Composers
2. Replace 2 Service Locator usages with DI
3. Extract search actions from ProductController