AutoForge/docs/architecture.md

182 lines
12 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.
## Current milestone status
Steps 04/04A/04B and 05/05A/05B are accepted. Step-06's display-unit
implementation and worker verification are complete and awaiting manual
orchestrator review; this status does not authorize Step-07.
```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 --> App[AutoForge.Application: cohesive feature slices]
Client --> App
App --> Diagnostics[AutoForge.Diagnostics: provider-neutral protocol and contracts]
App --> Core[AutoForge.Core: platform-neutral models]
Diagnostics --> Core
Client --> Simulation[AutoForge.Simulation: synthetic provider and transport]
Simulation --> Diagnostics
Simulation --> Core
UnitTests[AutoForge.UnitTests] --> Components
UnitTests --> Core
UnitTests --> App
UnitTests --> Diagnostics
UnitTests --> Simulation
IntegrationTests[AutoForge.IntegrationTests] --> UI
IntegrationTests --> App
IntegrationTests --> Core
IntegrationTests --> Diagnostics
IntegrationTests --> Simulation
```
## Projects and dependency boundaries
All nine 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/profile invariants and immutable dynamics configuration/status contracts | None |
| [Diagnostics](../src/AutoForge.Diagnostics/AutoForge.Diagnostics.csproj) | `net10.0`; provider/session/transport/control contracts, strict synthetic protocol v1/v2 client, typed results and bounded trace | Core |
| [Simulation](../src/AutoForge.Simulation/AutoForge.Simulation.csproj) | `net10.0`; validated static modules, fixed-step engine, isolated state, explicit provider factories and transports | Core, Diagnostics |
| [Application](../src/AutoForge.Application/AutoForge.Application.csproj) | `net10.0`; target/profile/diagnostic-session, dynamics-configuration, display-unit conversion and preference-port feature slices | Core, Diagnostics |
| [Components](../src/AutoForge.Components/AutoForge.Components.csproj) | `net10.0` RCL; generic `StatusNotice` and numeric/bar gauge with accessible state and safe rendering | None |
| [UI](../src/AutoForge.UI/AutoForge.UI.csproj) | `net10.0` RCL; all application routes, navigation, layout and presentation, including shared live dashboard editor | Application, Components, Diagnostics |
| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable and native preference adapter | Application, Simulation, UI |
| [UnitTests](../src/tests/AutoForge.UnitTests/AutoForge.UnitTests.csproj) | `net10.0`; Core/Application/contracts, protocol and reusable component tests | Application, Components, Core, Diagnostics, Simulation |
| [IntegrationTests](../src/tests/AutoForge.IntegrationTests/AutoForge.IntegrationTests.csproj) | `net10.0`; real DI, fixtures, provider transport/session and rendered UI/project-graph tests | Application, Components, Core, Diagnostics, Simulation, UI |
Components has no AutoForge project dependency. UI never references Client or
Simulation. Application never references Simulation, UI, Components or Client.
Core, Diagnostics and Simulation do not reference Application/UI/Client.
The static provider's DTC oracle is limited to IntegrationTests; the fixed-step
engine test surface is limited to UnitTests. Neither is part of production
Application/Diagnostics/UI contracts. There are
no cycles or production-to-test edges. Tests render UI directly and never
reference or launch Client.
The Client composes the unchanged static `SimulatedDiagnosticTransportFactory`
and the separate `DynamicsDiagnosticTransportFactory`. The static provider
remains `autoforge.simulation.synthetic` and uses strict protocol v1; the dynamics
provider is `autoforge.simulation.dynamics` and requires an explicit versioned
configuration, run identity, control capability and protocol-v2 frames.
`AddAutoForgeDiagnostics` registers both factory descriptors from the same
factory registrations used for transport resolution. Target
metadata resolution remains a separate, metadata-only action. The profile
catalog is process-local; importing does not select a revision or open a session.
Replay and physical kinds have no operational implementation and are never
substituted with Simulation.
## 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 synthetic diagnostic workflow and distinguishes it from dynamics and physical operations |
| `/execution-targets` | `Features/ExecutionTargets/SelectExecutionTarget/ExecutionTargetSelectionPage.razor` | Explicitly resolves registered provider metadata only; does not open a session |
| `/vehicle-profiles` | `Features/Vehicles/Profiles/VehicleProfilesPage.razor` | Explicit schema-v1 import, exact revision selection, metadata/provenance inspection and read-only export |
| `/diagnostics` | `Features/Vehicles/Diagnostics/DiagnosticsPage.razor` | Explicit saved profile/revision/provider/kind selection, static-v1 session lifecycle, separate expected/probed/identified counts, retained partial probe services, identity-gated DTC/static signal operations, clear acknowledgement plus fresh-empty-readback verification, raw/decoded trace, and the shared configurable live dashboard |
| `/simulation` | `Features/Vehicles/Simulation/SimulationPage.razor` | Explicit profile/config/provider selection, JSON import/export, stopped-by-default dynamics session, lifecycle/step/pacing/scenario controls, source/unit/quality/model-time/config/run-aware telemetry over diagnostic protocol v2, and the same session-bound live dashboard |
| Any unmatched route | `Features/Foundation/NotFoundPage.razor` via UI `Routes.razor` | Explicit not-found page and supported navigation |
The generic [StatusNotice](../src/AutoForge.Components/StatusNotice.razor)
provides accessible status/error feedback. The diagnostics page loads its
source-controlled synthetic profile example only after the user clicks its
import action; it does not select the new profile. Every operational action
requires an explicitly opened Simulation session. The page labels values as
static synthetic snapshots and exposes transport outcomes instead of treating
timeouts/no-responses as empty data.
Discovery preserves a validated positive probe independently from optional
profile-verified identity. Partial rows state the identity phase and reason;
advertised services alone never enable identity-dependent read/clear actions.
The shared live dashboard panel is UI composition over the Application
`ILiveDashboardFeed` for the page's actual `DiagnosticSession`; its reusable
numeric/bar renderer remains in Components and has no AutoForge dependency.
Bindings are offered only after identity-verified signal reads by that feed.
Definitions are in-memory (zero through eight gauges), use exact source units,
and are validated before replacing the current set. The shared display-unit
preference is persisted by the native Client through MAUI Preferences; portable
composition must supply an explicit store, and the UI-only unavailable store
reports failure rather than silently using memory. Conversions are a pure
presentation projection and never alter source snapshots, SI model state or
canonical gauge bounds. One feed polls once per
eligible module every cycle, independent of gauge visibility or render count.
The UI subscribes only for render notifications; hiding or disposing a panel
does not stop acquisition. The owning session and feature scope cancel and drain
the feed on close/replacement/disposal. See the [dashboard contract](live-dashboard.md)
for quality, range, sample-time and usage details.
The feature-local target-selection view model adapts explicit input to the
existing Application resolver. The same target resolver is populated from the
diagnostic factories' descriptors, so `/execution-targets` shows the actual
provider metadata without implying connection. Static sessions bind the exact
profile revision, vehicle and target. Dynamics identity additionally binds the
versioned configuration fingerprint and a separate operational run/session
identifier. Closing releases per-run engine, control and transport state;
reset opens a new session using the exact configuration snapshot held by the
original session, not a newer catalog selection.
The Application session use case keeps low-level `clear.dtcs` acknowledgement
distinct from verified clear. It performs a fresh read and only marks the
operation verified when the valid returned DTC list is empty. Failed or
nonempty readback remains a visible failure/uncertainty; valid remaining codes
are retained in the UI.
## Application and capability boundaries
The accepted target-selection use case remains grouped under
`Application/Features/ExecutionTargets/SelectExecutionTarget/`. It snapshots
registrations, rejects duplicate IDs using ordinal case-insensitive comparison,
resolves only exact requested metadata and preserves typed no-fallback failures.
The vehicle profile slice remains under `Application/Features/Vehicles/Profiles/`.
Core owns immutable profile identity/revision, vehicle facts, arbitrary module
roles, capability states and provenance context. Application owns strict
schema-v1 JSON interchange and an in-memory catalog with exact
`(profileIdentifier, revision)` selection. Existing schema-v1 profile JSON is
unchanged.
`AutoForge.Diagnostics` defines provider-neutral endpoint, transport, session,
protocol-client, logical-clock, operation-result, dynamics-control and trace
contracts. Protocol v1 remains the static diagnostics wire path. Protocol v2 is
an explicit dynamic telemetry path with a separate run/configuration-bound
payload; neither path dispatches through the other provider. Simulation owns
the numerical engine and diagnostic transports. Application owns configuration
import/export/catalog and session coordination; UI consumes shared controls and
diagnostic results only. The profile/module IDs, endpoint addresses and
identities are validated against the exact selected profile. See the [v1
guide](synthetic-diagnostics-v1.md), [v2 guide](synthetic-diagnostics-v2.md)
and [simulation guide](simulation.md).
## Honest limitations and safety boundaries
Implemented diagnostics and dynamics are synthetic, in-process and
Simulation-only. They prove encoded request/response handling and deterministic
model behavior, not vehicle compatibility, access, authenticity, real capture,
manufacturer accuracy or permission. Static v1 signals remain static. Protocol
v2 dynamic telemetry is computed from an explicitly configured simplified
model; it is not real sensor data or validated prediction. Virtual DTC clear
mutates only selected in-memory module/session state and has no physical write
path. No real vehicle, physical adapter, replay provider, programming,
calibration values, backups, AI, durable persistence or cloud service is
implemented. A `SUPPORTED` declaration, `VERIFIED` provenance label, physical
metadata kind or calibration reference does not implement or authorize an
operation.
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. [ADR-0004](adr-0004-synthetic-diagnostics.md) records
the Step-03 provider/protocol boundary. Worker completion remains distinct from
manual orchestrator acceptance.