AutoForge/docs/architecture.md

131 lines
7.9 KiB
Markdown

# Implemented architecture
## Application shape
AutoForge is an in-process modular monolith with exactly one application
executable: the Windows-first MAUI Blazor Hybrid Client. The application uses
Razor component libraries for the complete routed UI and generic shared controls.
There is no web/server host, WASM host or backend process.
```mermaid
flowchart TD
Client[AutoForge.Client: MAUI startup, BlazorWebView and DI] --> UI[AutoForge.UI: routes and feature presentation]
UI --> Components[AutoForge.Components: reusable generic UI]
UI --> Application[AutoForge.Application: cohesive feature slices]
Client --> Application
Application --> Core[AutoForge.Core: platform-neutral contracts]
UnitTests[AutoForge.UnitTests] --> Components
UnitTests --> Core
IntegrationTests[AutoForge.IntegrationTests] --> UI
IntegrationTests --> Application
IntegrationTests --> Core
```
## Projects and dependency boundaries
All seven projects are in [AutoForge.slnx](../src/AutoForge.slnx):
| Project | Target and responsibility | Project references |
|---|---|---|
| [Core](../src/AutoForge.Core/AutoForge.Core.csproj) | `net10.0`; platform-neutral target and immutable vehicle-profile/module/capability/provenance invariants | None |
| [Application](../src/AutoForge.Application/AutoForge.Application.csproj) | `net10.0`; target-selection and vehicle-profile import/catalog/select/export feature slices | Core |
| [Components](../src/AutoForge.Components/AutoForge.Components.csproj) | `net10.0` RCL; generic `StatusNotice` with accessible tone and safe text rendering | None |
| [UI](../src/AutoForge.UI/AutoForge.UI.csproj) | `net10.0` RCL; all application routes, navigation, layout and presentation | Application, Components |
| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable | Application, UI |
| [UnitTests](../src/tests/AutoForge.UnitTests/AutoForge.UnitTests.csproj) | `net10.0`; descriptor/resolver, rendered component, profile-domain and strict JSON tests | Application, Components, Core |
| [IntegrationTests](../src/tests/AutoForge.IntegrationTests/AutoForge.IntegrationTests.csproj) | `net10.0`; real DI, synthetic profile fixture, rendered RCL and actual project-graph tests | Application, Components, Core, UI |
Components has no AutoForge project dependency. UI never references Client.
Core and Application never reference UI/Components/Client or tests. There are no
cycles or production-to-test edges. Tests render UI directly and never reference
or launch Client.
The Client contains only MAUI lifecycle/startup, its Windows platform entry
point, the `BlazorWebView`, host HTML/CSS and in-process composition. It registers
an empty target metadata set deliberately, so the real selection use case reports
not-registered until an explicit future composition supplies real metadata.
Vehicle profiles use a distinct per-process in-memory catalog; importing one does
not register or alter an execution target. No fake connected/available provider
is added.
## UI ownership and real routes
All Razor routes and layouts are owned by the UI RCL; `Routes` scans the UI
assembly, not the native Client assembly.
| Route | UI owner | Implemented behavior |
|---|---|---|
| `/` | `Features/Foundation/Home.razor` | Describes the current foundation and accurately distinguishes implemented from absent features |
| `/execution-targets` | `Features/ExecutionTargets/SelectExecutionTarget/ExecutionTargetSelectionPage.razor` | Requires explicit provider identifier and target kind, calls the real injected application resolver and displays success/errors |
| `/vehicle-profiles` | `Features/Vehicles/Profiles/VehicleProfilesPage.razor` | Explicitly imports schema-v1 JSON, lists profile revisions, requires exact selection, renders metadata/provenance/unknowns and exposes read-only JSON export |
| Any unmatched route | `Features/Foundation/NotFoundPage.razor` via UI `Routes.razor` | Presents an explicit not-found page and supported navigation |
`Layout/MainLayout.razor` supplies main navigation, shared layout and a permanent
metadata-only limitation statement. The generic
[StatusNotice](../src/AutoForge.Components/StatusNotice.razor) is shared by the
home, target-selection, profile and not-found pages; isolated CSS bundles from both RCLs
are imported through the Client scoped-style bundle.
The target-selection page's feature-local `ExecutionTargetSelectionViewModel`
adapts explicit input to the existing Application resolver. It contains only
presentation state/input validation and expected error display; it does not
reimplement provider resolution. It receives the actual `IExecutionTargetResolver`
through DI. The same `AddAutoForgeTargetSelection` registration used in the
headless integration tests is composed by Client.
## Application feature organization
The accepted target-selection use case is grouped under
`Application/Features/ExecutionTargets/SelectExecutionTarget/`; its original
public namespace and API remain unchanged. Core still owns
`Simulation`, `RecordedReplay`, `PhysicalHardware` and immutable target descriptor
invariants. Application snapshots registrations, rejects duplicate IDs using
ordinal case-insensitive comparison, resolves only exact requested metadata and
returns the registered descriptor. Existing typed failures and no-fallback
behavior remain unchanged.
The vehicle profile slice is organized under
`Application/Features/Vehicles/Profiles/`. Core owns immutable profile identity
and revision, vehicle facts, arbitrary module roles, operation declarations,
capability states and provenance context. Application owns strict schema-v1
JSON interchange plus an in-memory catalog with explicit exact
`(profileIdentifier, revision)` selection. An import validates fully before it
registers; duplicate identities do not replace data. The Client catalog is
process-local and is not persistent.
The profile UI invokes the real import/list/select/export service through DI and
never auto-selects an imported/latest profile. Unknown optional facts remain
explicit `null`. Capability states and provenance are declarations only. Detailed
field, identifier, applicability and unknown-property rules are in the
[schema-v1 guide](vehicle-profile-schema-v1.md) and
[ADR-0003](adr-0003-profile-interchange-v1.md).
New use cases should be cohesive and independently testable slices. Each slice
owns its request/coordination and relevant application contract without forcing
unrelated projects to depend on Application. Domain engines/protocols remain
platform-neutral and can be extracted only when a real boundary warrants it.
Do not add mediator boilerplate, generic manager/repository layers or empty
future slices to demonstrate architecture.
## Honest limitations and safety boundaries
Current work implements application-shell/navigation behavior, accessible status
presentation, explicit execution-target metadata selection and **synthetic,
in-memory vehicle/module profile metadata interchange and selection**. The
profiles are not vehicle discovery or compatibility data. The product still does
not implement connection/discovery, simulation, diagnostics, telemetry, replay,
backups, calibration values/editing, persistent storage, AI, cloud services,
operation execution or hardware integration. A `SUPPORTED` declaration, a
`VERIFIED` provenance label, physical-kind metadata or a calibration reference
does not implement or authorize an operation.
Future simulation remains deterministic and AI-independent with an isolated
verification oracle. Future initial hardware integration is read-only. Physical
programming requires separate operation-specific authorization and evidence.
These are architectural requirements, not current app behavior.
The original [ADR-0001](adr-0001-headless-foundation.md) preserves valid foundation
decisions but marks its dual-shell/deferred-host decision superseded.
[ADR-0002](adr-0002-single-shell-vsa.md) is the current host and feature-slice
decision.