N-Tier Architecture Refactor — Orchestrator Planning Handoff

Updated: 2026-08-08 · Audited: 2026-08-03 · Epic: WI-2081 · Gap Analysis: WI-2104

Architecture Target State

ALPAMobile.Domain          ← Pure business rules, no external dependencies
ALPAMobile.Application     ← Service interfaces (contracts), orchestration/use-cases
ALPAMobile.Infrastructure  ← API clients, auth, storage, caching (implements Application interfaces)
ALPAMobile.Presentation    ← Pages, ViewModels, controls (depends on Application interfaces only)
ALPAMobile (MAUI host)     ← Composition root only — MauiProgram.cs wires everything via DI

Dependency rule (enforced by NetArchTest):

Domain ← Application ← Infrastructure
Domain ← Application ← Presentation
NEVER: Domain → anything, Application → Infrastructure/Presentation, Infrastructure → Presentation

Completed Work

• Resolved Phase 0 (WI-2082) — Guardrails & Architecture Tests (NetArchTest added, CI enforces layer boundaries)
• Resolved Phase 1 (WI-2083) — Layer Projects Scaffolded (Domain, Application, Infrastructure, Presentation projects exist and build)

Gap Tasks (WI-2104 Children)

Phase 2 — Domain Extraction (WI-2084)

Active Resolves Gap: WI-2108

Domain Model Strategy: Hybrid

• FTDT → Rich domain model: FTDTRecord and related entities own their own behavior (CalculateLimits(), IsValid(), etc.). FTDT is the core product, targeted as a shared library.
• All other entities → Anemic: Plain data containers; behavior in domain services.
• Future consideration: FTDT domain may be extracted into a standalone NuGet package (ALPAMobile.FTDT.Domain).

Known Specifics

• ALPAMobile/BusinessLogic/FTDTCalculator_USA.cs — migrate as rich domain behavior
• ALPAMobile/BusinessLogic/FTDTCalculator_CAN.cs — same
• ALPAMobile/BusinessLogic/FTDTCalculator_Shared.cs — same
• ALPAMobile/BusinessLogic/FTDTValidator.cs — same
• Audit all Models/ — identify which are domain entities vs. DTOs vs. API response models
• DTOs and API response models stay in Infrastructure or Application, not Domain

Constraints

• Do NOT move anything that references Microsoft.Maui, Preferences, Shell, or any service
• No [JsonProperty] or serialization attributes on Domain entities
• FTDT namespace must be structured for future NuGet extraction

Phase 3 — Application Layer & Interface Extraction (WI-2085)

New Resolves Gaps: WI-2105 (partial), WI-2111, WI-2112

ViewModel Conversion — 4-Batch Strategy

Key Interfaces to Define

• INavigationService (Application) — wraps Shell.Current navigation methods
• ISettingsService (Application) — user preferences that survive logout
• IUserAppDataService (Application) — runtime user app state, cleared on logout
• IDevDiagnosticsService (Application) — diagnostic mode, DEBUG builds only
• IDeviceTokenStore (Infrastructure) — Firebase/APNS tokens
• IInstallationService (Infrastructure) — installation key

Phase 4 — Infrastructure Layer (WI-2086)

New Resolves Gap: WI-2109

DataManager & RestService Decomposition

Phase 5 — Presentation Extraction (WI-2087)

New Resolves Gaps: WI-2106, WI-2107

This phase is a prerequisite for the UI Refresh (new component library + design system will be built on this clean surface).

• WI-2106 — Command modernization: 204 occurrences of new Command() across ViewModels → migrate to [RelayCommand] source-generated or explicit RelayCommand / AsyncRelayCommand
• WI-2107 — BindableBase replacement: ALPAMobile/Helpers/BindableBase.cs → migrate all ViewModels to ObservableObject from CommunityToolkit.Mvvm

Phase 6 — Composition Root Cleanup (WI-2088)

New Resolves Gap: WI-2105 (final closure)

Consolidate ALL DI registration into MauiProgram.cs. Remove ALL remaining service locator patterns.

builder.Services.AddDomainServices();
builder.Services.AddApplicationServices();
builder.Services.AddInfrastructureServices(builder.Configuration);
builder.Services.AddPresentationServices();

Phase 7 — SOLID Hardening (WI-2089)

New Resolves Gap: WI-2110

Validation infrastructure target:

// Application layer
public interface IValidationRule<T> { bool Check(T value); string ValidationMessage { get; } }
public class ValidatableObject<T> : ObservableObject { ... } // INotifyDataErrorInfo

Phase 8 — Test Coverage Strategy (WI-2090)

New

Tooling: NUnit 4.x + NSubstitute + Coverlet (unit) / NUnit 4.x + Appium v8 (UI) / NetArchTest.Rules (architecture)

Action required: Add NSubstitute NuGet reference to UnitTest.csproj

Sequencing & Dependencies

Phase 0 ✅ → Phase 1 ✅ → Phase 2 → Phase 3 → Phase 4
                                        ↓          ↓
                                    Phase 5    Phase 6
                                        ↓
                                    Phase 7
                                        ↓
                                    Phase 8

Critical path: Phase 3 (Application/DI) unlocks Phase 5 (Presentation) and Phase 6 (Composition Root). Phase 2 (Domain) can partially run in parallel with Phase 3.

UI Refresh intersection: Phase 5 is the gateway. The new component library / design system work should NOT begin until Phase 5 is complete.

Sub-Agent Guidance

1. Worktrees are required — each phase gets its own git worktree targeting DotNet10
2. Commit messages must include ADO link: feat: extract INavigationService and wire DI AB#2085 AB#2111
3. PR target: imp/blazor-hybrid branch always (was DotNet10 when this plan was written)
4. Architecture test gate: Run NetArchTest suite after every migration step
5. Phase 3 ViewModel batching: 4 PRs in order — Auth → MEC/LEC → FTDT/Jumpseat → Nav/UI
6. Review before merge: Dr. Castro reviews all PRs before merge to DotNet10

ADO Work Item Reference

AppProperties Decomposition (WI-2113)

Analysis confirmed: AppProperties is NOT a settings class — it mixes three distinct concerns:

Sequencing note: IUserAppDataService interface is defined in Phase 3, but its LiteDB-backed implementation requires WI-2109 (Phase 4) to be complete first.