AutoForge/docs/architecture.md

6.3 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.

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:

Project Target and responsibility Project references
Core net10.0; platform-neutral explicit target-kind and immutable descriptor invariants None
Application net10.0; in-process application use cases, organized by feature Core
Components net10.0 RCL; generic StatusNotice with accessible tone and safe text rendering None
UI net10.0 RCL; all application routes, navigation, layout and presentation Application, Components
Client net10.0-windows10.0.26100.0; only MAUI Blazor Hybrid application executable Application, UI
UnitTests net10.0; descriptor/resolver and rendered generic component tests Application, Components, Core
IntegrationTests net10.0; real DI, rendered RCL, application 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. 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
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 is shared by the home, target-selection 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.

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 and metadata selection only. It does not implement vehicle profiles, connection/discovery, simulation, diagnostics, telemetry, replay, backups, calibration, persistence, AI, cloud services, operation execution or hardware integration. Physical-kind metadata neither connects nor grants a capability/write approval.

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 preserves valid foundation decisions but marks its dual-shell/deferred-host decision superseded. ADR-0002 is the current host and feature-slice decision.