Layered Architecture of vorssaint-utils: A 5-Layer Swift Architecture Explained

Vorssaint-utils implements a classic five-layer architecture comprising Presentation, Service, Core, System-Integration, and Application Entry Point layers, ensuring strict separation between UI rendering, business logic, and low-level macOS system calls.

Vorssaint-utils adopts a rigorous layered architecture that organizes macOS utility functionality into five distinct tiers. This architectural pattern, implemented throughout the vorssaint/vorssaint-utils repository, enables the application to deliver comprehensive menu-bar utilities while maintaining testable, isolated components and declarative SwiftUI interfaces.

The Five Layers Defined

The codebase separates concerns into five hierarchical layers, each with well-defined responsibilities and communication patterns.

1. Presentation (UI) Layer

The Presentation layer handles all user interface rendering using SwiftUI. It contains View structs for panels, menus, dialogs, and tool windows, remaining strictly declarative and free of business logic.

Key files in this layer include:

• Sources/Vorssaint/UI/MenuPanel/MenuPanelView.swift – Renders the main menu panel interface
• Sources/Vorssaint/UI/Settings/SettingsView.swift – Provides the application settings interface

2. Service (Business Logic) Layer

Services encapsulate all core functionality through ObservableObject classes that expose @Published state and actions. This layer contains feature-specific managers handling audio, window layout, clipboard operations, and fan control.

Notable implementations include:

• Sources/Vorssaint/Services/Audio/AppVolumeMixer.swift – Manages per-application audio mixing
• Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift – Controls window positioning and management

These services act as the intermediary between UI components and lower-level system operations.

3. Core (Model & Utilities) Layer

The Core layer defines shared data structures, localization support, permissions handling, and thin wrappers around macOS APIs. It provides the data models and utility functions consumed by Services.

Critical files in this tier:

• Sources/Vorssaint/Core/Permissions.swift – Handles macOS permission states and requests
• Sources/Vorssaint/Core/Localization.swift – Manages string localization and internationalization

4. System-Integration Layer

This layer provides low-level bindings to macOS system libraries not included in the Swift standard library. Compiled as system library targets, these components link directly into the executable for hardware-level operations.

Key components include:

• Sources/HIDEventSystem/include/HIDEventSystem.h – C headers for hardware input device events
• Sources/VMStatisticsCompat – Helpers for virtual memory statistics retrieval

5. Application Entry Point

The entry layer bootstraps the application, injects service objects into the SwiftUI environment, and configures global hot-key and appearance handling.

Essential files:

• Sources/Vorssaint/main.swift – Application bootstrap and initialization
• Sources/Vorssaint/App/AppAppearanceController.swift – Manages system appearance integration
• Sources/Vorssaint/App/FeatureRuntime.swift – Coordinates feature initialization and lifecycle

Layer Interaction Flow

The architecture enforces unidirectional dependencies where each layer communicates only with adjacent tiers. The interaction flow follows this pattern:

1. main.swift instantiates the top-level VorssaintApp and injects service singletons (such as AppSwitcher and ShelfService) into the SwiftUI environment object hierarchy.

2. UI views (MenuPanelView, SettingsView) bind to these services via @EnvironmentObject or @ObservedObject. User interactions (button taps, toggles) trigger method calls on the service objects.

3. Services execute business logic, calling into the Core layer for data models (e.g., Permissions) or the System-Integration layer for hardware operations (e.g., volume changes via AppVolumeMixer).

4. When services update their @Published state, SwiftUI automatically triggers view redraws, synchronizing the interface with system state.

Code Example: Flow Through the Architecture

The following implementation illustrates how a "Keep Awake" feature traverses all five layers:

// 1️⃣ Presentation Layer – SwiftUI toggle
struct KeepAwakeToggle: View {
    @EnvironmentObject var keepAwake: KeepAwakeManager
    var body: some View {
        Toggle("Keep Awake", isOn: $keepAwake.isEnabled)
    }
}

// 2️⃣ Service Layer – Business logic manager
final class KeepAwakeManager: ObservableObject {
    @Published var isEnabled = false {
        didSet { updateSystem() }
    }
    private func updateSystem() {
        PowerManager.shared.setPreventSleep(isEnabled)
    }
}

// 3️⃣ Core Layer – macOS API wrapper
final class PowerManager {
    static let shared = PowerManager()
    func setPreventSleep(_ enabled: Bool) {
        SystemPowerAPI.setAssertion(enabled)
    }
}

In this flow, the UI layer remains strictly declarative, while the Service layer manages state mutations and the Core layer handles the actual macOS Power Management API interactions.

Summary

• Vorssaint-utils organizes code into five distinct layers: Presentation, Service, Core, System-Integration, and Application Entry Point.
• SwiftUI views in the Presentation layer bind to ObservableObject services via @EnvironmentObject, maintaining declarative UI patterns.
• The Service layer contains all business logic, exposing @Published properties that drive UI updates while isolating system interactions.
• Core utilities provide shared models and thin API wrappers, while the System-Integration layer handles C-library bindings for hardware access.
• This separation ensures that UI code remains lightweight and testable, with heavy lifting isolated in dedicated service and system layers.

Frequently Asked Questions

How does the Presentation layer communicate with business logic in vorssaint-utils?

The Presentation layer communicates exclusively through SwiftUI property wrappers. Views such as MenuPanelView access service objects via @EnvironmentObject or @ObservedObject, binding directly to @Published properties on classes like KeepAwakeManager or AppVolumeMixer. This ensures the UI remains reactive without containing imperative business logic.

What responsibilities does the Service layer handle?

The Service layer encapsulates all observable state and core functionality, including audio management, window layout, clipboard operations, and fan control. Services expose methods that UI components call in response to user actions, then coordinate with the Core and System-Integration layers to execute platform-specific operations.

Which macOS APIs does the System-Integration layer wrap?

The System-Integration layer provides Swift bindings for low-level macOS frameworks not available in the standard library, including hardware input device events via HIDEventSystem.h and virtual memory statistics through VMStatisticsCompat. These system library targets compile as C headers with Swift bridging modules for direct hardware access.

Why are Core and Service layers separated in the architecture?

The separation ensures that shared data structures (Permissions, L10n) and API wrappers remain independent of business logic lifecycle management. While Services maintain observable state and user-facing functionality, the Core layer provides pure data models and utility functions that multiple services can import without creating circular dependencies or UI coupling.

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