How Vorssaint's Modular Feature Architecture Works: A Technical Deep Dive

Vorssaint implements a plug-in-style system where every discrete capability is represented by a feature, coordinated through a pure catalog and lazy runtime bridge that instantiates services only when enabled.

The vorssaint/vorssaint-utils repository powers Vorssaint's macOS productivity suite with an elegant modular feature architecture. This design separates static capability descriptions from live service management, enabling zero-overhead inactive features and straightforward extensibility. Here's how the three-layer system works under the hood.

The Three Core Components

Feature Catalog: Pure Static Descriptions

The Feature Catalog lives in Sources/Vorssaint/Core/FeatureCatalog.swift and defines every possible capability as an AppFeature enum case. Each case's raw String value serves as a stable persistence key for availability in UserDefaults.

// Sources/Vorssaint/Core/FeatureCatalog.swift#L15-L33
enum AppFeature: String, CaseIterable {
    // Windows and Dock
    case switcher, dockPreview, dockClick, windowMaximizer, windowLayout, autoQuit
    // Mouse and keyboard
    case scrollInverter, focusFollowsMouse, smoothScroll, mouseAcceleration,
         mouseNavigation, mouseButtonShortcuts, middleClick,
         mouseClickDebounce, keyboardDebounce, textSnippets, superKey,
         quitWindowProtection
    // … (other categories omitted for brevity)
}

Features are organized into FeatureGroup enums for UI presentation. The catalog remains pure—no runtime behavior, only metadata. This separation allows version control diffing and inspection without triggering recompilation of service code.

Feature Runtime: Lazy Service Instantiation

The Feature Runtime at Sources/Vorssaint/App/FeatureRuntime.swift bridges catalog entries to live service instances through a bindings dictionary. Each AppFeature maps to a closure that creates or tears down its concrete service.

// Sources/Vorssaint/App/FeatureRuntime.swift#L73-L84
private static let bindings: [AppFeature: () -> Void] = [
    .switcher: {
        WindowUseTracker.shared.syncWithFeatures()
        AppSwitcher.shared.syncWithPreferences()
    },
    .dockPreview: { DockPreviewService.shared.syncWithPreferences() },
    // … (other bindings omitted)
]

Critically, these closures are lazy. They execute only when a feature becomes available, not at app launch. The syncAtLaunch() method iterates all features but calls bindings conditionally:

// Sources/Vorssaint/App/FeatureRuntime.swift#L50-L56
func syncAtLaunch() {
    for feature in AppFeature.allCases where feature.isAvailable {
        Self.bindings[feature]?()
    }
}

This guarantees that disabled features consume zero memory or CPU cycles.

Availability and Hardware Validation

Availability operates as a layer above individual feature enable flags. Two factors determine whether a feature runs:

• User preference: Stored via UserDefaults using feature.rawValue as the key
• Hardware support: Computed lazily through hardwareUnsupportedReason

// Sources/Vorssaint/App/FeatureRuntime.swift#L98-L106
extension AppFeature {
    var hardwareUnsupportedReason: String? {
        switch self {
        case .fanControl:
            return FanControlHardware.hasControllableFan
                ? nil : FeatureStrings.fanControl(L10n.shared.language).noFans
        default: return nil
        }
    }
    var isHardwareSupported: Bool { hardwareUnsupportedReason == nil }
}

Hardware checks stay out of the catalog, preserving its purity. The runtime evaluates isAvailable (user flag and hardware support) before invoking any binding.

Runtime Behavior: Launch and Toggling

Startup Sequence

When Vorssaint launches, FeatureRuntime.shared.syncAtLaunch() executes:

1. Iterates AppFeature.allCases
2. Filters to features where feature.isAvailable returns true
3. Executes the corresponding bindings closure
4. The closure typically calls syncWithPreferences() on a singleton service

Services like WindowLayoutService.shared or DockPreviewService.shared initialize only at this point, not during app binary loading.

Dynamic Toggling

User interaction triggers FeatureRuntime.setAvailable(_: Bool):

// Turn on the clipboard history feature
FeatureRuntime.shared.setAvailable(.clipboardHistory, true)

// Turn off fan control (may require relaunch to fully unload)
FeatureRuntime.shared.setAvailable(.fanControl, false)

This method:

• Updates the persisted availability flag
• Adds the feature to loadedThisSession if it was previously active (tracking unload requirements)
• Immediately runs the binding to spin up or tear down the service

Features that require full process termination to unload cleanly trigger the restart banner through this tracking mechanism.

Adding a New Feature: The Three-Step Pattern

Vorssaint's modular feature architecture enables new capabilities through a consistent boilerplate. Here's adding a hypothetical Quick Notes feature:

Step 1: Extend the catalog

// Sources/Vorssaint/Core/FeatureCatalog.swift
enum AppFeature: String, CaseIterable {
    // … existing cases …
    case quickNotes   // ← new entry
}

Step 2: Create the service

// Sources/Vorssaint/Features/QuickNotes/QuickNotesService.swift
final class QuickNotesService {
    static let shared = QuickNotesService()
    private init() {}
    
    func syncWithPreferences() {
        // Load user defaults, start background monitoring, etc.
    }
}

Step 3: Register the binding

// Sources/Vorssaint/App/FeatureRuntime.swift
private static let bindings: [AppFeature: () -> Void] = [
    // … existing bindings …
    .quickNotes: { QuickNotesService.shared.syncWithPreferences() },
]

After rebuild, the feature surfaces in the hub UI, respects hardware checks, and instantiates QuickNotesService only when toggled on.

Key Architectural Files

File	Purpose
Sources/Vorssaint/Core/FeatureCatalog.swift	Static AppFeature enum, grouping, and permission definitions
Sources/Vorssaint/App/FeatureRuntime.swift	Runtime singleton, lazy bindings, availability handling, hardware checks
Sources/Vorssaint/Core/Defaults.swift	DefaultsKey constants for persistence
Sources/Vorssaint/Core/FeatureStrings.swift	Localized UI strings (titles, descriptions, tooltips)

These four files constitute the complete modular feature system: pure catalog, runtime bridge, persistence layer, and localization support.

Design Strengths

• Zero overhead: Inactive features never allocate memory or register observers
• Type safety: Swift's exhaustive enum checking prevents unhandled features
• Testability: Pure catalog enables snapshot testing; runtime permits mock service injection
• Extensibility: New capabilities require only catalog entry, service class, and binding registration
• Hardware adaptability: Per-feature hardware checks gracefully degrade on incompatible Macs

Summary

• Feature Catalog (FeatureCatalog.swift) defines all capabilities as a pure AppFeature enum with raw-value persistence keys
• Feature Runtime (FeatureRuntime.swift) manages lazy instantiation through a bindings dictionary that executes only for available features
• Availability layer combines user preference (UserDefaults) and hardware support (hardwareUnsupportedReason) to determine feature eligibility
• Service pattern requires singletons implementing syncWithPreferences() for initialization on demand
• Three-step extension (catalog entry, service class, binding registration) enables new features without architectural changes

Frequently Asked Questions

How does Vorssaint prevent disabled features from consuming resources?

The bindings dictionary stores closures, not service instances. When syncAtLaunch() runs, it iterates all AppFeature cases but executes a binding only if feature.isAvailable returns true. This lazy evaluation means disabled features never trigger service allocation, observer registration, or background processing. The closure itself is a lightweight static reference until invoked.

What happens when a user toggles a feature that requires hardware support?

The runtime checks isHardwareSupported before reflecting any UI state. If hardwareUnsupportedReason returns a non-nil string (e.g., "No controllable fans detected" for .fanControl), the feature appears disabled in the hub with an explanatory tooltip. The availability flag persists, but the binding never executes. If hardware later becomes compatible, the existing preference activates automatically.

Why does disabling some features require an app restart?

Certain services register global event taps, kernel extensions, or persistent background tasks that cannot be cleanly released within the running process. When setAvailable(_: false) detects the feature was loaded this session via loadedThisSession tracking, it sets needsRestartToUnload. The UI displays a restart banner rather than attempting unsafe teardown. Users can continue working; the change applies on next launch.

Can third-party developers extend Vorssaint with custom features?

The current architecture is internal to the vorssaint-utils repository. While the three-step pattern (catalog, service, binding) is straightforward, extending it requires modifying core source files. The design prioritizes maintainability and compile-time safety over dynamic plug-in loading. Future versions could expose a formal extension API by externalizing the bindings registration mechanism through a public protocol.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}