Runtime Bootstrap

Runtime Bootstrap

Runtime bootstrap is the production entry path that moves Forsetti from a plain SwiftUI launch to an activated Forsetti runtime with one selected UI module and all service/feature lifecycle modules running.

Boot Objects

Object	Responsibility
ForsettiApp	SwiftUI @main entry point. Creates the runtime bootstrap as a @StateObject.
ForsettiProductionRootView	Displays loading, ready, or failure state. Shows DashboardView only after successful boot.
ForsettiRuntimeBootstrap	Owns boot state, runtime setup, service registration, manifest catalog loading, factory registration, activation, and error reporting.
ForsettiApplicationServices	Creates and holds the app-level service aggregate.
ForsettiFrameworkContainer	Creates credentials, authentication, API gateway, diagnostics, dashboard module registry, and package manager.
ForsettiModuleCatalog	Loads runtime manifests and resolves manifests by entry point.
ForsettiLifecycleModule	Shared base class for simple runtime lifecycle modules.

Boot State Machine

stateDiagram-v2
    [*] --> notStarted
    notStarted --> booting: bootForProduction()
    booting --> ready: manifests loaded and modules activated
    booting --> failed: manifest, registry, runtime, or activation error
    failed --> booting: retry
    ready --> ready: repeated boot call is ignored

Loading

Production Boot Sequence

sequenceDiagram
    participant App as ForsettiApp
    participant Root as ForsettiProductionRootView
    participant Boot as ForsettiRuntimeBootstrap
    participant Catalog as ForsettiModuleCatalog
    participant Runtime as ForsettiRuntime
    participant Manager as ModuleManager
    participant Diag as DiagnosticsCenter

    App->>Root: create root view with bootstrap
    Root->>Boot: bootForProduction()
    Boot->>Catalog: load manifests from ForsettiManifests
    Catalog-->>Boot: manifests by module ID and entry point
    Boot->>Runtime: boot(bundle, manifestsSubdirectory)
    Runtime-->>Boot: discovered manifest set
    loop production service modules
        Boot->>Manager: activateModule(moduleID)
        Manager-->>Boot: module started
    end
    Boot->>Manager: activate UI module
    Boot->>Manager: setSelectedUIModule(retail UI)
    Boot-->>Root: bootState = ready
    Root-->>App: render DashboardView
    alt failure
        Boot->>Diag: report runtime_boot failure
        Boot-->>Root: bootState = failed(error)
        Root-->>App: render retryable failure view
    end

Loading

Initialization Pipeline

flowchart TD
    Init["ForsettiRuntimeBootstrap.init"] --> AppServices["ForsettiApplicationServices.makeDefault()"]
    AppServices --> Container["ForsettiFrameworkContainer()"]
    Container --> Diagnostics["DiagnosticsCenter"]
    Container --> Credentials["JamfCredentialsStore"]
    Container --> Auth["JamfAuthenticationService"]
    Container --> Gateway["JamfAPIGateway"]
    Container --> RegistryUI["Dashboard ModuleRegistry"]
    Container --> PackageManager["ModulePackageManager.bootstrap()"]
    Init --> ServiceContainer["ForsettiServiceContainer"]
    ServiceContainer --> PlatformDefaults["DefaultForsettiPlatformServices"]
    PlatformDefaults --> PublicServices["Networking, Storage, SecureStorage, FileExport, Telemetry"]
    ServiceContainer --> Markers["Authentication, Diagnostics, API, Security marker services"]
    Init --> RuntimeRegistry["ForsettiCore.ModuleRegistry"]
    RuntimeRegistry --> Factories["Entry-point factories"]
    Init --> Runtime["ForsettiRuntime"]

Loading

Manifest Discovery

Runtime manifests live under ForsettiApp/Resources/ForsettiManifests. The catalog indexes them two ways:

• manifestsByID: validates module IDs and activation lists.
• manifestsByEntryPoint: resolves concrete factory registrations.

Every manifest entry point must have exactly one factory:

Entry point	Runtime class
ForsettiRetailUIModule	ForsettiRetailUIModule
ForsettiJamfServiceModule	ForsettiJamfServiceModule
ForsettiDiagnosticsServiceModule	ForsettiDiagnosticsServiceModule
ForsettiScannerServiceModule	ForsettiScannerServiceModule
ForsettiComputerSearchModule	ForsettiComputerSearchModule
ForsettiMobileDeviceSearchModule	ForsettiMobileDeviceSearchModule
ForsettiSupportTechnicianModule	ForsettiSupportTechnicianModule
ForsettiPrestageDirectorModule	ForsettiPrestageDirectorModule
ForsettiReportsModule	ForsettiReportsModule
ForsettiDeploymentTrackerModule	ForsettiDeploymentTrackerModule
ForsettiPermissionsMatrixModule	ForsettiPermissionsMatrixModule

Activation Order

flowchart LR
    Boot["boot runtime"] --> Jamf["Jamf service"]
    Jamf --> Diagnostics["Diagnostics service"]
    Diagnostics --> Scanner["Scanner service"]
    Scanner --> Computer["Computer Search"]
    Computer --> Mobile["Mobile Device Search"]
    Mobile --> Support["Support Technician"]
    Support --> Prestage["PreStage Director"]
    Prestage --> Reports["Reports"]
    Reports --> Deployment["Deployment Tracker Demo"]
    Deployment --> Permissions["Permissions Helper"]
    Permissions --> UI["Retail UI"]
    UI --> Selected["Selected UI module"]

Loading

The runtime uses restoreActivationState: false during production boot. First boot explicitly activates the required module set and selects com.forsetti.jamfpro.retail.ui.

Error Handling

Boot errors are not swallowed. If manifest loading, factory registration, runtime boot, or module activation fails:

1. bootState becomes .failed(error).
2. DiagnosticsCenter records a forsetti.runtime / bootstrap error.
3. ForsettiProductionRootView shows a native failure screen.
4. The user can retry boot from the failure screen.

Idempotency Rules

• Repeated bootForProduction() calls return immediately after a successful boot.
• Concurrent boot requests await the same boot task.
• Lifecycle modules ignore duplicate start(context:) calls once started.
• Lifecycle modules tolerate stop(context:) after partial or absent start.

Pseudocode Shape

@MainActor
func bootForProduction() async {
    guard didBoot == false else { return }
    bootState = .booting
    do {
        _ = try await runtime.boot(
            bundle: bundle,
            manifestsSubdirectory: "ForsettiManifests",
            restoreActivationState: false
        )

        for moduleID in ForsettiModuleCatalog.productionServiceModuleIDs {
            try await runtime.moduleManager.activateModule(moduleID: moduleID)
        }

        try await runtime.moduleManager.activateModule(
            moduleID: ForsettiModuleCatalog.uiModuleID
        )
        try runtime.moduleManager.setSelectedUIModule(
            moduleID: ForsettiModuleCatalog.uiModuleID
        )

        didBoot = true
        bootState = .ready
    } catch {
        bootState = .failed(error)
        await reportBootFailure(error)
    }
}