A contract-first modular runtime with strict, directional boundaries for native Apple development.
Forsetti is not a convention or a pattern library. It is a runtime framework that enforces modular architecture through strict package boundaries and runtime policy — from module discovery and compatibility validation through entitlement-gated activation to host-mediated UI contribution.
How Forsetti Works
The framework operates as a layered runtime pipeline. Each stage enforces specific guarantees before the next stage begins.
Discovery
The runtime loads the bundled JSON manifests shipped with your app and indexes each module by ID. Every module declares its identity, version, supported platforms, requested capabilities, and runtime requirements through its manifest.
Validation
The CompatibilityChecker validates each module against its schema and template version, supported platforms, the Forsetti version range, and the host capability policy, and confirms its registration record still matches the manifest. Modules that fail are rejected before any code executes.
Entitlement Check
Compatible modules are checked against the entitlement provider, which decides via its unlock check whether the module may proceed. A module can carry a product ID; a locked module stays discovered but inactive.
Activation
Unlocked modules have their identity and runtime requirements validated, then the runtime calls start(context:) with a capability-scoped context. If start throws, the module is rolled back and activation fails cleanly.
UI Contribution
The active UI or app module publishes structured UI contributions. The runtime validates and sanitizes them, the UISurfaceManager publishes the surface state, and the host renders the approved data through its own layout.
Design Principles
Native-First
Built entirely on Swift and SwiftUI. No bridging layers and no cross-platform abstractions — Forsetti is a native Apple framework that integrates directly with the platform toolchain: Xcode, Swift Package Manager, and Apple developer workflows.
Contract-First
Every module ships two aligned contracts — a Swift protocol and a bundled JSON manifest — that must describe the same module before it can activate. Capabilities, requirements, and contributions are all declared up front, with no implicit coupling or hidden dependencies.
Boundary-First
Dependencies run in one direction: lower layers never import higher layers, and crossing a boundary means going through protocols, manifests, service injection, or events. Architecture tests enforce the import direction in CI, and apps build on the public package products — never on framework internals.
Policy-First
Activation is governed by policy, not just availability. A capability policy decides what each module may request and the entitlement provider decides whether it is unlocked — enabling licensing, feature gating, and capability-scoped access at the runtime level.
Validation-First
Compatibility is verified before activation, not discovered through runtime failures. Each module is validated against its schema and template version, supported platforms, the Forsetti version range, and requested capabilities. Incompatible modules are cleanly rejected with structured compatibility reports.
Composition-First
Applications are composed from independent modules, not built as monoliths. Service modules run concurrently while exactly one UI or app module stays active by default, and the runtime composes them into one coherent application experience.
Runtime Architecture
ForsettiRuntime composes a set of cooperating components, each responsible for a specific part of discovery, validation, activation, and UI composition.
ForsettiRuntime
The top-level runtime facade. Boots the framework from your app bundle and owns the event bus, UI surface manager, module manager, overlay router, and entitlement provider.
ManifestLoader
Loads and validates the bundled JSON manifests, checking required fields, schema and template pairing, runtime-requirement shape, and duplicate module IDs.
CompatibilityChecker
Produces a compatibility report for each module from its schema and template version, supported platforms, the Forsetti version range, and the host capability policy.
ModuleManager
Registers discovered manifests and stores a hash of each for drift detection, then validates identity and runtime requirements, activates and deactivates modules, persists state, and keeps exactly one UI module active.
ModuleRegistry
Maps each manifest entryPoint string to a Swift factory that builds the module instance. A discovered manifest with no matching factory cannot activate.
UISurfaceManager
Publishes the validated contributions of the active UI module — toolbar items, slot-based view injections, and overlay schema — as host-readable surface state.
Platform Support
iOS
Full support for iOS 17 and later. Build modular iPhone and iPad apps with structured, SwiftUI-based UI contribution and StoreKit-backed entitlements.
macOS
Native support for macOS 14 and later. Compose desktop apps from independent modules, with SwiftUI-based UI contribution and a host shell you own.
Swift & Xcode
Built for Swift 5.10 and Swift Package Manager. Integrates with standard Xcode workflows and uses the Swift type system to enforce module contracts.
Explore the module system.
Learn how modules are structured, how contracts are defined, and how the runtime manages the full module lifecycle.