Module System
Modules are the fundamental unit of composition in Forsetti. Each module declares its capabilities through a contract, implements a standard interface, and participates in a governed lifecycle managed by the runtime.
IForsettiModule Interface
Every module implements the IForsettiModule abstract base class. This contract defines the lifecycle methods the runtime uses to manage module state transitions.
class IForsettiModule {
public:
virtual ~IForsettiModule() = default;
virtual std::string identifier() const = 0;
virtual std::string displayName() const = 0;
virtual SemanticVersion version() const = 0;
virtual ActivationResult activate(const ActivationContext& ctx) = 0;
virtual void deactivate() = 0;
virtual ModuleCapabilities capabilities() const = 0;
virtual ModuleType moduleType() const = 0;
};Module Types
Service Module
Provides backend services and business logic without a user interface. Registers services with the service container and responds to events through the event bus. Examples: data sync, analytics, caching.
UI Module
Contributes visual elements to the host application through structured extension points. Provides WinUI 3 views for toolbar items, view injections, and overlay routing. May also register services.
App Module
A full application module that combines service logic and UI contributions into a cohesive feature. Manages its own internal state and lifecycle while contributing to the host through defined contracts.
Module Lifecycle
Every module transitions through five governed states. The runtime controls each transition and enforces validation at every boundary.
Discovered
The module has been found by the runtime scanner and its manifest has been loaded. The module is cataloged but has not yet been checked for compatibility.
Validated
The module has passed compatibility validation. Its manifest is well-formed, its dependencies are satisfied, and it meets the host platform requirements.
Entitled
The module has passed entitlement checks. Its required capabilities are covered by available entitlements and the access policy permits activation.
Active
The module is fully activated and running. Its services are registered, its UI contributions are live, and it participates in the event bus.
Deactivated
The module has been cleanly shut down. Its services are unregistered, its UI contributions are removed, and its resources are released.
Manifest Format
Each module declares its contract through a JSON manifest. The manifest defines the module identity, type, version, capabilities, dependencies, and compatibility requirements.
{
"identifier": "com.forsetti.example.service",
"displayName": "Example Service Module",
"version": "1.0.0",
"type": "service",
"capabilities": [
"storage",
"telemetry",
"networking"
],
"dependencies": [],
"compatibility": {
"minHostVersion": "1.0.0",
"platform": "windows"
},
"entitlements": [
"storage.read",
"storage.write",
"telemetry.send"
]
}UI Contribution Model
UI modules contribute visual elements through structured extension points defined by the host application. The contribution model ensures modules cannot inject arbitrary UI — only fill declared slots.
Toolbar Items
Modules contribute toolbar actions through declared contribution points. The host assembles toolbar items from active modules according to priority and capability contracts.
View Injections
Modules inject WinUI 3 views into named slots defined by the host layout. View injections are type-safe and validated against the host contribution schema.
Overlay Routing
Modules register overlay routes for modal and sheet presentations. The routing overlay manager handles navigation stack management and transition coordination.
Built-in Capabilities
Modules declare which capabilities they require. The runtime and entitlement system use these declarations to enforce access control.
storage
Read and write access to persistent storage through the Windows Registry or file system abstraction layer.
telemetry
Ability to emit telemetry events and diagnostic data through the framework telemetry pipeline.
routing_overlay
Permission to register overlay routes for modal presentations, sheets, and navigation transitions.
toolbar_items
Permission to contribute toolbar actions and controls to the host application toolbar surface.
view_injection
Permission to inject WinUI 3 views into named host layout slots through the UI surface manager.
networking
Access to network operations through the WinHTTP-based networking service provided by the platform layer.
secure_storage
Access to DPAPI-encrypted binary data storage for sensitive configuration and credential management.
file_export
Permission to export binary data and documents to the file system through the platform export service.
ui_theme_mask
Framework-reserved capability for UI theme customization and visual appearance control across modules.
event_publishing
Permission to publish events on the framework event bus for decoupled inter-module communication.
Build your first module.
Follow the documentation to create a module from scratch, or explore the reference implementations on GitHub.