Architecture

Architecture

Forsetti Framework - Windows is organized around a strict one-way dependency model. ForsettiCore is the authority layer; platform adapters, host composition, examples, samples, tests, and scripts realize or validate core contracts without redefining them.

Layer Model

flowchart TB
    Demo["samples/ForsettiDemo\ndownstream sample"]
    Host["ForsettiHostTemplate\nsealed host composition layer"]
    Platform["ForsettiPlatform\nWindows SDK adapters"]
    Core["ForsettiCore\npure C++20 runtime"]
    ServiceExample["ForsettiExampleServiceModule"]
    UIExample["ForsettiExampleUIModule"]
    AppExample["ForsettiExampleAppModule"]
    Tests["Native test suites\nCore, Platform, Architecture"]
    Scripts["Scripts\nlocal guardrails"]

    Demo --> Host
    Demo --> ServiceExample
    Demo --> UIExample
    Demo --> AppExample
    Host --> Platform
    Host --> Core
    Platform --> Core
    ServiceExample --> Core
    UIExample --> Core
    AppExample --> Core
    Tests --> Core
    Tests --> Platform
    Scripts -.verify.-> Core
    Scripts -.verify.-> Platform
    Scripts -.verify.-> Host
    Scripts -.verify.-> ServiceExample
    Scripts -.verify.-> UIExample
    Scripts -.verify.-> AppExample

    classDef core fill:#e8f4ff,stroke:#1f5f99,color:#102a43;
    classDef platform fill:#f0fff4,stroke:#2f855a,color:#123524;
    classDef host fill:#fff7e6,stroke:#b7791f,color:#3d2b12;
    classDef reference fill:#f7fafc,stroke:#4a5568,color:#1a202c;
    class Core core;
    class Platform platform;
    class Host host;
    class Demo,ServiceExample,UIExample,AppExample,Tests,Scripts reference;

Loading

Layer Responsibilities

Layer	Status	Responsibilities	Allowed Dependencies
ForsettiCore	active	Module model, manifest parsing, schema/template 1.1, compatibility checks, runtime requirement validation, registration records, capability policy, scoped context, event bus, service container, activation state, UI contribution models, UI surface manager, runtime orchestration	C++20 standard library, nlohmann/json
ForsettiPlatform	active	Windows SDK implementations for core service interfaces, registry-backed module registration, CNG-backed manifest digests, and Windows view factory registration	ForsettiCore, Windows SDK libraries
ForsettiHostTemplate	active	Host bootstrap, controller, launch strategy, overlay router, host state snapshots, and surface state adaptation	ForsettiCore, ForsettiPlatform
Example modules	active	Separate service, UI, and app reference modules with owned manifests	ForsettiCore
samples/ForsettiDemo	active	Downstream composition root that wires the host template and example modules	Host and example targets
tests	active	Native CppUnitTest coverage and architecture scanning	Tested libraries
Scripts	active	Local build/test/guardrail verification and repository automation helpers	PowerShell, local Python for repository automation

Dependency Rule R006

Dependencies flow downward only. Core must not import platform, host, examples, samples, or test-only surfaces.

flowchart LR
    Core["ForsettiCore"]
    Platform["ForsettiPlatform"]
    Host["ForsettiHostTemplate"]
    Examples["Example modules"]
    Demo["ForsettiDemo"]

    Platform --> Core
    Host --> Platform
    Host --> Core
    Examples --> Core
    Demo --> Host
    Demo --> Examples

    Core -. forbidden .-> Platform
    Core -. forbidden .-> Host
    Core -. forbidden .-> Examples
    Platform -. forbidden .-> Host
    Platform -. forbidden .-> Examples
    Examples -. forbidden .-> Platform
    Examples -. forbidden .-> Host

Loading

Source	Must Not Include
ForsettiCore	ForsettiPlatform, ForsettiHostTemplate, example modules, samples
ForsettiPlatform	ForsettiHostTemplate, example modules, samples
ForsettiHostTemplate	example modules, samples
Example modules	ForsettiPlatform, ForsettiHostTemplate, other example modules, samples

The rule is enforced by:

• tests/ForsettiArchitectureTests/ArchitectureEnforcementTests.cpp
• Scripts/check-architecture.ps1
• Scripts/check-dependencies.ps1
• CMake target link boundaries

Runtime Component Graph

flowchart TB
    Runtime["ForsettiRuntime"]
    Manager["ModuleManager"]
    Loader["ManifestLoader"]
    Registry["ModuleRegistry"]
    StaticRegistry["ForsettiStaticModuleRegistry"]
    Registration["ModuleRegistrationService"]
    Requirements["ModuleRequirementValidator"]
    Checker["CompatibilityChecker"]
    Policy["ICapabilityPolicy"]
    Entitlements["IEntitlementProvider"]
    Store["IActivationStore"]
    Context["ForsettiContext"]
    Services["IServiceProvider"]
    ScopedServices["CapabilityScopedServiceProvider"]
    EventBus["IForsettiEventBus"]
    Logger["IForsettiLogger"]
    Router["IOverlayRouter"]
    Guard["IModuleCommunicationGuard"]
    Surface["UISurfaceManager"]

    Runtime --> Manager
    Runtime --> Entitlements
    Runtime --> EventBus
    Manager --> Loader
    Manager --> Registry
    Manager --> Registration
    Manager --> Requirements
    StaticRegistry --> Registry
    Manager --> Checker
    Checker --> Policy
    Requirements --> Services
    Manager --> Entitlements
    Manager --> Store
    Manager --> Context
    Manager --> Surface
    Context --> ScopedServices
    ScopedServices --> Services
    Context --> EventBus
    Context --> Logger
    Context --> Router
    Context --> Guard

Loading

Repository Layout

Path	Description
include/ForsettiCore	Public core interfaces and value types.
src/ForsettiCore	Core implementation.
include/ForsettiPlatform	Public platform adapter declarations.
src/ForsettiPlatform	Windows SDK platform services, registration store, digest provider, and view factory registry.
include/ForsettiHostTemplate	Public host bootstrap, controller, overlay router, state, and surface adapter contracts.
src/ForsettiHostTemplate	Sealed host composition implementation.
src/ForsettiExampleServiceModule	Reference service module and manifest.
src/ForsettiExampleUIModule	Reference UI module and manifest.
src/ForsettiExampleAppModule	Reference app module and manifest.
samples/ForsettiDemo	Downstream demonstration composition root.
templates	Windows module and host starter templates.
tests/ForsettiCoreTests	Runtime, model, registration, context, compatibility, manifest, logging, and UI tests.
tests/ForsettiPlatformTests	Windows service adapter tests.
tests/ForsettiArchitectureTests	Dependency scanning tests.
Scripts	Local verification and repository automation scripts.
docs/governance	Discussion automation and moderation policy.
.forsetti/alignment	Runtime-boundary alignment reports and blocked native-validation evidence.

Design Consequences

• Core contracts must be testable without WinUI or Windows UI dependencies.
• Platform adapters implement service interfaces; they do not redefine module lifecycle rules.
• Host composition is sealed and depends on Core plus Platform only.
• Example modules are reference modules, not privileged runtime participants.
• Build and guardrail scripts are checks, not substitutes for runtime enforcement.