Home

Forsetti Framework Wiki

Forsetti is an Apple-native modular runtime framework for iOS and macOS applications. It gives a host app a controlled way to discover, validate, unlock, activate, and render modules while keeping dependency direction explicit.

Last updated: June 18, 2026

Reader promise: this wiki is the comprehensive operating manual. It explains the architecture, runtime logic, module workflows, UI contribution model, entitlement gates, testing guardrails, and production handoff process.

Navigation Map

Need	Start Here	Outcome
Understand the system	Architecture Overview	Know the targets, dependency direction, and runtime roles.
Pick a deployment shape	Integration Patterns	Choose Pattern A, B, C, or D without mixing responsibilities.
Build a module	Module Model and Manifests	Create a module class, manifest, registry entry, and lifecycle implementation.
Wire app UI	Host UI and Surfaces	Connect toolbar items, view injections, overlays, and active UI modules.
Gate paid features	Entitlements and Capabilities	Enforce unlock state and capability policy before activation.
Understand releases	Versioning and Releases	Follow SemVer, PR-time version updates, and release handoff.
Ship safely	Testing and Guardrails	Run the checks that protect package boundaries and runtime behavior.

System at a Glance

flowchart LR
    App["Host App<br/>SwiftUI or AppKit shell"] --> HostTemplate["ForsettiHostTemplate<br/>Controller and views"]
    App --> Runtime["ForsettiRuntime"]
    Runtime --> Registry["ModuleRegistry<br/>entry-point factories"]
    Runtime --> Loader["ManifestLoader<br/>bundled JSON manifests"]
    Runtime --> Manager["ModuleManager<br/>registration and activation"]
    Runtime --> Entitlements["EntitlementProvider<br/>StoreKit or static"]
    Runtime --> Services["ServiceContainer<br/>host-owned adapters"]
    Manager --> Surface["UISurfaceManager<br/>composite UI state"]
    Manager --> Registration["RegistrationStore<br/>manifest identity records"]
    Manager --> Modules["App, UI, and service modules"]
    Modules --> Context["ForsettiContext<br/>services, events, logging, routing"]
    Context --> EventBus["EventBus"]
    Context --> Logger["Logger"]

Loading

Forsetti sits between the host application and app-owned modules. The host owns platform services, policy, and presentation. Modules own feature behavior and declare their integration contract through manifests.

What Makes Forsetti Different

Principle	What It Means in Practice
Contract first	Every module has a manifest and a public entry point before it can activate.
Boundary first	Lower-level targets do not import upper-level targets; app code does not patch framework internals.
Runtime policy	Compatibility, capabilities, and entitlements are evaluated before lifecycle code runs.
Structured UI	Modules contribute toolbar actions, view injections, overlays, and declared UI IDs through data contracts.
Native first	Swift, SwiftPM, SwiftUI, StoreKit, Foundation, and Apple-native platform services are the intended path.
Single active UI	Service modules can run concurrently, while the default UI/app model keeps exactly one active UI module.
Scoped services	Modules resolve host services through capability-scoped contexts.

Runtime Storyboard

sequenceDiagram
    participant Host as Host App
    participant Runtime as ForsettiRuntime
    participant Loader as ManifestLoader
    participant Manager as ModuleManager
    participant Ent as Entitlements
    participant Module as Module
    participant UI as UISurfaceManager

    Host->>Runtime: boot(bundle, manifestsSubdirectory)
    Runtime->>Loader: load manifests
    Loader-->>Runtime: manifest map
    Runtime->>Ent: refreshEntitlements()
    Runtime->>Manager: restore persisted activation
    Host->>Manager: activateModule(moduleID)
    Manager->>Manager: compatibility report and registration check
    Manager->>Ent: isUnlocked(moduleID, productID)
    Ent-->>Manager: unlocked or locked
    Manager->>Manager: validate identity, runtime requirements, and capabilities
    Manager->>Module: start(scoped context)
    Manager->>UI: apply UI contributions
    Manager-->>Host: refreshed state

Loading

Package Products

Product	Depends On	Primary Responsibility
ForsettiCore	none	Runtime contracts, manifest model, compatibility checks, activation, events, logging, UI contribution state.
ForsettiPlatform	ForsettiCore	StoreKit-backed entitlements and default platform service adapters.
ForsettiHostTemplate	ForsettiCore, ForsettiPlatform	Reusable SwiftUI host controller, shell views, overlay router, and view injection registry.

ForsettiModulesExample remains an internal target for examples and tests, but it is not exposed as a public package product.

Current Documentation Set

Page	Why It Exists
Architecture Overview	Target graph, boundary model, and runtime component responsibilities.
Runtime Lifecycle	Boot, discovery, activation, restore, entitlement reconciliation, and shutdown.
Module Model and Manifests	Protocols, manifest schema, module types, validation rules, and authoring workflow.
Integration Patterns	Production and testing deployment shapes with diagrams.
Host UI and Surfaces	Toolbar, view injection, overlay schema, and surface composition.
Entitlements and Capabilities	StoreKit/static entitlement behavior and capability policy gates.
Services, Events, and Diagnostics	Dependency injection, event bus, module messaging, and logging.
Xcode Templates	Production starter template, module templates, install scripts, and development mode.
Testing and Guardrails	Test suites, CI checks, architecture enforcement, and pre-merge expectations.
Operational Workflows	Manual wiki maintenance, releases, version updates, and consumer integration workflows.
Versioning and Releases	SemVer rules, PR-time version updates, workflow behavior, and release handoff.
Security, Privacy, and Reliability	Secure integration practices and performance expectations.
Troubleshooting	Common failure modes, root causes, and fixes.
API Reference	Public types, responsibilities, and usage notes.
Glossary and Checklists	Shared vocabulary and implementation checklists.

Non-Negotiable Integration Rule

Use Forsetti through public package products and public APIs. Build app-owned modules outside the framework. Do not copy framework source into an app target, patch internals for app-specific behavior, or create backdoor dependencies from app code into framework implementation details.