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

> Explore Vorssaint's modular feature architecture. Discover how features, a catalog, and a lazy runtime bridge enable plug-in capabilities for the vorssaint-utils repository. Learn more.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: deep-dive
- Published: 2026-09-06

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`.

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.

```swift
// 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:

```swift
// 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`

```swift
// 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)`:

```swift
// 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**

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

```

**Step 2: Create the service**

```swift
// 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**

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift) | Static `AppFeature` enum, grouping, and permission definitions |
| [`Sources/Vorssaint/App/FeatureRuntime.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/FeatureRuntime.swift) | Runtime singleton, lazy bindings, availability handling, hardware checks |
| [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift) | `DefaultsKey` constants for persistence |
| [`Sources/Vorssaint/Core/FeatureStrings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift)) defines all capabilities as a pure `AppFeature` enum with raw-value persistence keys
- **Feature Runtime** ([`FeatureRuntime.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.