AutoForge/docs/adr-0002-single-shell-vsa.md

4.1 KiB

ADR-0002: One native shell, two RCLs, feature-oriented application

  • Date: 2026-10-28
  • Status: accepted 2026-10-28; extended by accepted Step-02 profile slice
  • Supersedes: ADR-0001's dual-shell and deferred-host decision only
  • Scope: initial application composition and organization

Context

The accepted Step-01 foundation provides real, headless Core/Application target-selection behavior and regression tests, but no host or UI. The owner subsequently realigned the architecture before Step-02: add a usable Windows-first native application now, keep work in-process and use vertical feature slices without unnecessary hosting/infrastructure layers. Preserve the accepted target-selection feature and every original regression behavior.

Decision

  1. The sole initial application executable is AutoForge.Client, a .NET 10 MAUI Blazor Hybrid app initially targeting Windows x64.
  2. AutoForge.UI, a net10.0 RCL, owns the complete application routes, pages, navigation, layout and feature presentation. AutoForge.Components, a separate net10.0 RCL, owns generic reusable controls.
  3. Use exactly the primary production dependency path Client -> UI -> Components. UI calls application contracts; Client composes the real existing Application feature in-process. Dependencies on Application needed for composition/presentation are direct; neither UI nor Client is substituted by a web/server host.
  4. Preserve Core as platform-neutral and organize Application behavior by cohesive, independently testable feature slices. The existing target selection lives at Features/ExecutionTargets/SelectExecutionTarget without changing its public namespace or wrapping it in mediator/handler boilerplate.
  5. Headless unit/integration tests compile and render Components/UI/Application independently of MAUI. The native Client references those same real RCLs and application registration; tests do not mock the feature/component under test.
  6. Initial routes are / (foundation), /execution-targets (explicit metadata selection), and an explicit not-found presentation. Selection requires a provider identifier and defined kind, resolves only registered metadata, and never means connection, capability or operation authorization.
  7. Keep the application startable without backend, database, vehicle, native driver, model, cloud account or service. The Client registers an empty real provider list; the UI communicates ProviderNotRegistered explicitly rather than fabricating a connected provider.
  8. Add future features only when assigned and owned: domain engines remain independent, slices coordinate their relevant use cases, and additional processes/hosts require a concrete requirement and approval.

Consequences

  • The four original Core/Application/test projects and all 54 accepted tests are retained. The solution now contains seven projects including the one native executable and two purposeful RCLs.
  • A MAUI Windows workload, Windows SDK and WebView2 runtime are real native build/ run prerequisites. RCL compilation and headless tests do not substitute for native Client build/smoke evidence.
  • The standalone Blazor WebAssembly plus MAUI Hybrid dual-shell plan and Step-05 host deferral recorded in ADR-0001 are superseded; ADR-0001's platform-neutral foundation, dependency direction, explicit target and no-fallback decisions remain valid.
  • No empty automotive feature directory, simulation/diagnostic/AI service, server process, database, cloud service, generic manager/repository layer or mediator is introduced.
  • Future simulation remains deterministic and AI-independent with isolated verification. Future initial hardware integration is read-only; neither selection nor simulated approval grants physical write authority.

See the implemented architecture and build/test policy for source paths and concrete evidence. Step-02 adds a profile metadata slice without changing this shell boundary; its schema and catalog rules are recorded in ADR-0003.