Umbraco-CMS/docs/plans/2025-12-19-contentservice-refactor-design-critical-review-1.md

# Critical Architectural Review: ContentService Refactoring Design

**Reviewed Document:** `docs/plans/2025-12-19-contentservice-refactor-design.md`
**Review Date:** 2025-12-19
**Reviewer Role:** Senior Principal Software Architect

---

## 1. Overall Assessment

**Strengths:**
- Correctly identifies a real maintainability problem (~3800 lines monolith)
- Preserves backward compatibility via facade pattern (essential for Umbraco ecosystem)
- Clear separation by functional domain (CRUD, Publishing, Move)
- Aligns with Umbraco's existing layered architecture (interfaces in Core, implementations in Infrastructure)

**Major Concerns:**
- **Naming collision** with existing `ContentPublishingService` already in codebase
- **Cross-service transaction coordination** inadequately addressed
- **Arbitrary public/internal distinction** doesn't match actual usage patterns
- **Missing mapping** for several existing methods that don't fit cleanly into proposed services

---

## 2. Critical Issues

### 2.1 Naming Collision with Existing ContentPublishingService

**Description:** A `ContentPublishingService` already exists at `src/Umbraco.Core/Services/ContentPublishingService.cs:16` with interface `IContentPublishingService`. The proposed `IContentPublishingService` would directly conflict.

**Impact:** Build failure or confusing namespace disambiguation; existing consumers of `IContentPublishingService` would break or become ambiguous.

**Suggestion:** Rename the proposed interface to `IContentPublishOperationService` or `IContentPublicationService`, OR refactor the existing `ContentPublishingService` to use the new infrastructure.

---

### 2.2 Cross-Service Dependencies Create Circular Risk

**Description:** The proposed services have intrinsic coupling:
- `MoveToRecycleBin` (Move) fires `ContentUnpublishedNotification` for published content (requires Publishing awareness)
- `Publish` (Publishing) calls `Save` internally (requires CRUD)
- `Copy` (Move) calls `Save` and checks `GetPermissions` (requires CRUD and Permissions)

**Impact:** Either circular dependencies between services OR the facade must orchestrate complex multi-service operations, defeating decomposition benefits.

**Suggestion:** Extract a shared `ContentOperationOrchestrator` that coordinates cross-cutting operations, or make Publishing/Move depend on CRUD (unidirectional), with explicit dependency documentation.

---

### 2.3 Transaction Boundary Ownership Unclear

**Description:** The design states "Ensure scopes work across service calls" but doesn't specify:
- Who creates the scope when `ContentMoveService.MoveToRecycleBin` needs to unpublish content?
- Can services assume they're called within an existing scope, or must each method create its own?
- How do nested scope behaviors work when Service A calls Service B?

**Impact:** Inconsistent transaction handling could lead to partial commits, audit log inconsistencies, or notification ordering issues.

**Suggestion:** Define explicit scope ownership rules:
- **Option A:** All public service methods create their own scope (simple, but nested operations may have issues)
- **Option B:** Services accept optional `ICoreScope` parameter for caller-managed transactions
- **Option C:** Use ambient scope pattern consistently (document the pattern)

---

### 2.4 Arbitrary Public vs Internal Classification

**Description:** The design classifies:
- **Public:** CRUD, Publishing, Move
- **Internal:** Versioning, Query, Permission, Blueprint

But examining actual usage:
- `GetVersions`, `Rollback`, `DeleteVersions` are public on `IContentService`
- `GetPermissions`, `SetPermissions` are public on `IContentService`
- `GetPagedChildren`, `GetAncestors`, `Count` are frequently used externally
- Blueprints have public API methods

**Impact:** Internal helpers cannot be injected by consumers who need specific functionality. Forces continued use of `IContentService` facade for everything.

**Suggestion:** Either:
- Make Query and Versioning public (they represent distinct concerns API consumers need)
- OR keep all as internal and document that `IContentService` remains the public API (current approach but explicitly stated)

---

### 2.5 Missing Method Mappings

**Description:** Several existing methods don't cleanly map to proposed services:

| Method | Proposed Location | Problem |
|--------|------------------|---------|
| `SendToPublication` | ? | Not listed, involves Save + events |
| `CheckDataIntegrity` | ? | Not listed, infrastructure concern |
| `DeleteOfTypes` | CRUD? Move? | Moves children to bin, then deletes |
| `CommitDocumentChanges` | Publishing? | Internal but critical for scheduling |
| `GetPublishedChildren` | Query? Publishing? | Uses Published status (domain crossover) |

**Impact:** Implementation will encounter methods that don't fit, leading to ad-hoc placement or leaky abstractions.

**Suggestion:** Create explicit method-to-service mapping table covering ALL 80+ methods in current `IContentService`. Identify "orchestration" methods that may stay in facade.

---

### 2.6 Notification Consistency Risk

**Description:** ContentService fires ~20 different notification types (`ContentSaving`, `ContentPublishing`, `ContentMoving`, etc.) with specific state propagation via `WithStateFrom()`. Splitting services means:
- Each service must correctly fire its subset of notifications
- State must be preserved across service boundaries
- Notification ordering must remain consistent

**Impact:** Breaking notification contracts would affect cache invalidation, webhooks, search indexing, and third-party packages.

**Suggestion:** Add explicit notification responsibility matrix to design. Consider a `ContentNotificationService` that centralizes notification logic, called by all sub-services.

---

## 3. Alternative Architectural Challenge

### Alternative: Vertical Slicing by Operation Complexity

Instead of horizontal domain slicing (CRUD/Publishing/Move), slice vertically by operation complexity:

**Proposed Structure:**
1. `ContentReadService` - All read operations (Get, Count, Query, Versions read-only)
2. `ContentWriteService` - All simple mutations (Create, Save, Delete)
3. `ContentWorkflowService` - All complex stateful operations (Publish, Unpublish, Schedule, Move, MoveToRecycleBin)

**Pro:** Matches actual dependency patterns - reads are independent, writes have minimal coupling, workflows can depend on both. Simpler transaction model.

**Con:** Workflows service could still grow large; doesn't solve the "where does Copy go" problem.

---

## 4. Minor Issues & Improvements

### 4.1 Line Count Estimates May Be Optimistic

The `ContentPublishingService` is estimated at ~800 lines, but `CommitDocumentChangesInternal` alone is 330+ lines with complex culture/scheduling logic. Consider splitting publishing into Immediate vs Scheduled sub-components.

### 4.2 Missing Async Consideration

Existing `EmptyRecycleBinAsync` suggests async patterns are emerging. New services should define async-first interfaces where database operations are involved.

### 4.3 No Explicit Interface for ContentServiceBase

The design shows `ContentServiceBase` as abstract class but doesn't specify if it implements any interface. Consider `IContentServiceBase` for testing.

### 4.4 Helper Naming Convention

"Helper" suffix is discouraged in modern .NET. Consider `ContentVersionManager`, `ContentQueryExecutor`, etc.

---

## 5. Questions for Clarification

1. **Existing IContentPublishingService:** Should the current `ContentPublishingService` be refactored to use the new infrastructure, replaced, or renamed?

2. **Branch Publishing:** The complex `PublishBranch` operation (200+ lines) spans publishing AND tree traversal. Which service owns it?

3. **Locking Strategy:** Current code uses explicit `scope.WriteLock(Constants.Locks.ContentTree)`. Will each sub-service acquire locks independently, or is there a coordination pattern?

4. **Culture-Variant Complexity:** The `CommitDocumentChangesInternal` method handles 15+ different publish result types with culture awareness. Is this complexity remaining in one place or distributed?

5. **RepositoryService Base Class:** Current `ContentService : RepositoryService`. Do new services also inherit this, or get dependencies differently?

---

## 6. Final Recommendation

### Major Revisions Needed

The design addresses a real problem and the overall direction is sound, but implementation will hit significant obstacles without addressing the following:

| Priority | Action Item | Status |
|----------|-------------|--------|
| **P0** | Resolve naming collision with existing `ContentPublishingService` | Required |
| **P0** | Document transaction/scope ownership explicitly | Required |
| **P0** | Create complete method mapping covering all 80+ IContentService methods | Required |
| **P1** | Define notification responsibility matrix per service | Required |
| **P1** | Reconsider public/internal classification based on actual API usage patterns | Recommended |
| **P1** | Address cross-service dependency direction (who can call whom) | Recommended |

Once these are addressed, the refactoring approach is viable and would meaningfully improve maintainability.

---

## Appendix: Key Files Reviewed

- `src/Umbraco.Core/Services/ContentService.cs` (3824 lines)
- `src/Umbraco.Core/Services/IContentService.cs` (522 lines, ~80 methods)
- `src/Umbraco.Core/Services/ContentPublishingService.cs` (existing, conflicts with proposal)
- `src/Umbraco.Core/CLAUDE.md` (architecture patterns reference)