How Utility Functions Are Organized in vorssaint-utils: A Layered Swift Architecture

The vorssaint-utils utility functions are organized into three logical layers: a top-level entry point, a Core directory for reusable business logic, and a UI directory for SwiftUI components, with additional standalone modules for system integrations.

The vorssaint/vorssaint-utils repository is a Swift-based macOS utility collection that demonstrates clean separation of concerns through its deliberate directory structure. Understanding how utility functions are organized helps developers navigate the codebase, extend functionality, and maintain the project effectively.

Top-Level Entry Point

Every Swift application needs a clear launch mechanism. In vorssaint-utils, this resides at Sources/Vorssaint/main.swift. This file serves as the application bootstrap, initializing the core systems and presenting the initial UI.

The minimal surface area of the entry point keeps startup logic isolated from implementation details, following the single-responsibility principle.

Core Utilities Layer

The Sources/Vorssaint/Core/ directory contains the bulk of reusable utility functions. Each file focuses on one specific concern, making discovery and maintenance straightforward.

URL and String Processing

// Sources/Vorssaint/Core/URLCleaning.swift
let raw = "https://example.com///path?query=1"
let cleaned = URLCleaning.clean(raw)
// Result: "https://example.com/path?query=1"

The URLCleaning.swift module provides URL normalization—removing redundant slashes and standardizing formats for consistent downstream processing.

System Integration Helpers

• SymbolicHotKeys.swift – Abstracts macOS symbolic hot-key APIs into a type-safe Swift interface
• Permissions.swift – Centralizes app-level permission checks (Accessibility, Screen Recording, etc.)
• ReleaseNotes.swift – Bundles version history and changelog strings
• RecorderStrings.swift – Provides localized UI text for screen recording features

The naming convention is intentional: files ending in *Strings.swift contain string resources, while *Support.swift files implement functional helpers. This pattern scales across the dozen-plus files in the Core directory.

Using Core Utilities from Higher Layers

import VorssaintCore

struct HotKeyButton: View {
    var body: some View {
        Button("Activate SuperKey") {
            SymbolicHotKeys.activate(.superKey)
        }
    }
}

The Core layer exports no UI dependencies, making it testable and reusable across contexts.

UI Layer Organization

The Sources/Vorssaint/UI/ directory implements the presentation layer using SwiftUI and AppKit. It mirrors the Core structure by feature rather than function type.

Feature-Based UI Subdirectories

Feature	Key File	Purpose
Window management	WindowGestureControls.swift	Custom window-switching gestures
Release communications	UpdateHighlightsView.swift	Update notification UI
Application removal	Uninstall/UninstallerView.swift	Guided uninstall wizard
Application removal	Uninstall/AppPickerView.swift	Target selection for uninstall
Visual consistency	Theme.swift	Global color and typography definitions

All UI components consume string resources from the Core layer, enforcing strict separation between presentation and data. The Uninstall/ subdirectory demonstrates how complex flows receive dedicated folders.

import SwiftUI
import VorssaintCore

struct ReleaseNotesView: View {
    var body: some View {
        Text(ReleaseNotes.latest)
            .padding()
    }
}

Standalone Helper Modules

Beyond the main application, three auxiliary modules provide specialized system integrations:

NowPlayingAdapter

Sources/NowPlayingAdapter/NowPlayingAdapter.swift bridges macOS "Now Playing" media information into the application. This module isolates Media Remote framework dependencies from the main codebase.

HIDEventSystem

The Sources/HIDEventSystem/ module contains low-level HID event handling with a C header at include/HIDEventSystem.h. This exposes kernel-grade input event processing to Swift callers through a clean boundary layer.

FanControlHelper

A minimal utility at Sources/FanControlHelper/main.swift providing macOS SMC fan control operations. Its independent entry point allows execution outside the main application context.

Complete Directory Structure

Sources/
├─ Vorssaint/
│   ├─ main.swift                 ← App entry point
│   ├─ Core/                      ← Pure utility logic & string bundles
│   │   ├─ URLCleaning.swift
│   │   ├─ SymbolicHotKeys.swift
│   │   ├─ Permissions.swift
│   │   ├─ ReleaseNotes.swift
│   │   └─ RecorderStrings.swift
│   └─ UI/                        ← SwiftUI / AppKit components
│       ├─ WindowGestureControls.swift
│       ├─ UpdateHighlightsView.swift
│       ├─ Theme.swift
│       └─ Uninstall/
│           ├─ UninstallerView.swift
│           └─ AppPickerView.swift
├─ NowPlayingAdapter/             ← Media integration
│   └─ NowPlayingAdapter.swift
├─ HIDEventSystem/                ← Low-level HID bindings
│   └─ include/HIDEventSystem.h
└─ FanControlHelper/              ← Standalone fan utilities
    └─ main.swift

Summary

• Entry point isolation – Sources/Vorssaint/main.swift handles only application launch
• Core directory – All reusable utility functions organized by single responsibility (URLCleaning, SymbolicHotKeys, Permissions, etc.)
• UI directory – Feature-based SwiftUI components that import Core but never implement business logic
• Standalone modules – NowPlayingAdapter, HIDEventSystem, and FanControlHelper for system-level integrations
• Naming conventions – *Strings.swift for resources, *Support.swift for helpers, subdirectory nesting for complex features

This organization makes specific utilities discoverable by purpose and maintains clean boundaries between layers.

Frequently Asked Questions

Where is the main application entry point in vorssaint-utils?

The entry point is Sources/Vorssaint/main.swift. This file initializes the application and delegates to the Core and UI layers without containing implementation logic itself.

How do I find a specific utility function in the codebase?

Check Sources/Vorssaint/Core/ first. Files are named by their primary concern—URL handling lives in URLCleaning.swift, permission checks in Permissions.swift, and hot-key management in SymbolicHotKeys.swift. The consistent naming pattern makes targeted searches effective.

Can Core utilities be used without the UI layer?

Yes. The Core directory has no dependencies on SwiftUI or AppKit, allowing standalone import for command-line tools, tests, or extensions. The FanControlHelper module demonstrates this pattern with its independent main.swift.

What is the purpose of the NowPlayingAdapter module?

Sources/NowPlayingAdapter/NowPlayingAdapter.swift provides a Swift interface to macOS Media Remote framework data. It isolates the complexity of private API interop from the main application, reducing coupling and simplifying updates when system APIs change.

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