159 lines
10 KiB
Markdown
159 lines
10 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 --> 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 and dynamics-configuration feature slices | Core, Diagnostics |
|
|
| [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, Diagnostics |
|
|
| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable | 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, and raw/decoded trace |
|
|
| `/simulation` | `Features/Vehicles/Simulation/SimulationPage.razor` | Explicit profile/config/provider selection, JSON import/export, stopped-by-default dynamics session, lifecycle/step/pacing/scenario controls, and source/unit/quality/model-time/config/run-aware telemetry over diagnostic protocol v2 |
|
|
| 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 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.
|