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

70 lines
4.1 KiB
Markdown

# 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](architecture.md) and
[build/test policy](build-and-test.md) 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](adr-0003-profile-interchange-v1.md).