215 lines
14 KiB
Markdown
215 lines
14 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, 05/05A/05B and 06/06A are accepted. Step-07 adds bounded
|
|
session-owned capture, strict local archive readback and shared host controls.
|
|
The nine-project Release build, full test suite and native capture/save/restart/
|
|
readback smoke are complete. Step-07 worker status remains pending manual
|
|
orchestrator review.
|
|
|
|
```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, live-dashboard and telemetry-recording/archive 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 dashboard and recording/archive inspection controls | Application, Components, Diagnostics |
|
|
| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable, native preference adapter and app-local archive root | 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, shared live dashboard and session recording/archive inspection |
|
|
| `/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 dashboard and recording/archive controls |
|
|
| 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 shared recording panel consumes the Application
|
|
`TelemetryRecordingWorkspace`, not the live dashboard feed or its bounded
|
|
200-entry UI trace. Diagnostics publishes immutable observations after each
|
|
validated trace commit; a capture subscribes to that actual operation stream
|
|
for one explicit session, preserving request/response bytes and attaching only
|
|
the successful `read.signals` result from the same operation. Start excludes
|
|
prior history; Stop detaches and drains already-dispatched callbacks. The
|
|
capture is memory-only until explicit Stop and Save, bounded at 4,096
|
|
observations, 16 MiB encoded observations, 1 MiB encoded header and 32 MiB
|
|
archive input/output. A rejected next observation freezes an explicitly
|
|
incomplete prefix. Close/reset stops capture but retains the old source context
|
|
for inspection/save. UI unmount does not own or stop capture.
|
|
Stopped, failed or discarded capture owners are removed from the diagnostic
|
|
session's lifetime-resource list; the workspace retains only the current
|
|
inspection/save data. An active capture is still drained on source close.
|
|
|
|
The Client persists only explicitly saved archives under its app-local
|
|
`recordings` directory. Application owns schema-v1 validation and file-storage
|
|
contracts; save writes and flushes a task-specific temporary file before
|
|
no-overwrite publication. Readback uses a new store instance and does not
|
|
rebind profiles or sessions. The format preserves capture elapsed time,
|
|
diagnostic logical ticks and model time as distinct values. This is local
|
|
archive persistence, not live disk streaming, crash durability, cryptographic
|
|
authenticity or playback. V2 archive checks share the source validator for
|
|
signal IDs, units, JSON kinds and finite values; v1 retains its opaque value
|
|
contract. Missing first-use storage is an empty catalogue, while invalid roots,
|
|
listing failures and save failures remain visible. See the
|
|
[archive-v1 guide](telemetry-archive-v1.md).
|
|
|
|
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, live streaming, crash-durable capture or cloud
|
|
service is implemented. Saved recordings are local source-sensitive files and
|
|
must be treated as potentially sensitive data. 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.
|