AutoForge/docs/architecture.md

12 KiB

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.

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:

Project Target and responsibility Project references
Core net10.0; platform-neutral target/profile invariants and immutable dynamics configuration/status contracts None
Diagnostics net10.0; provider/session/transport/control contracts, strict synthetic protocol v1/v2 client, typed results and bounded trace Core
Simulation net10.0; validated static modules, fixed-step engine, isolated state, explicit provider factories and transports Core, Diagnostics
Application net10.0; target/profile/diagnostic-session, dynamics-configuration, display-unit conversion and preference-port feature slices Core, Diagnostics
Components net10.0 RCL; generic StatusNotice and numeric/bar gauge with accessible state and safe rendering None
UI net10.0 RCL; all application routes, navigation, layout and presentation, including shared live dashboard editor Application, Components, Diagnostics
Client net10.0-windows10.0.26100.0; only MAUI Blazor Hybrid application executable and native preference adapter Application, Simulation, UI
UnitTests net10.0; Core/Application/contracts, protocol and reusable component tests Application, Components, Core, Diagnostics, Simulation
IntegrationTests 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 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 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, v2 guide and simulation guide.

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 preserves valid foundation decisions but marks its dual-shell/deferred-host decision superseded. ADR-0002 is the current host and feature-slice decision. ADR-0004 records the Step-03 provider/protocol boundary. Worker completion remains distinct from manual orchestrator acceptance.