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

> Discover the layered Swift architecture of vorssaint-utils. Learn how utility functions are organized into entry points, Core business logic, UI components, and system integrations.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: architecture
- Published: 2026-09-05

---

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

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/URLCleaning.swift) module provides **URL normalization**—removing redundant slashes and standardizing formats for consistent downstream processing.

### System Integration Helpers

- **[`SymbolicHotKeys.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SymbolicHotKeys.swift)** – Abstracts macOS symbolic hot-key APIs into a type-safe Swift interface
- **[`Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Permissions.swift)** – Centralizes app-level permission checks (Accessibility, Screen Recording, etc.)
- **[`ReleaseNotes.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ReleaseNotes.swift)** – Bundles version history and changelog strings
- **[`RecorderStrings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) | Custom window-switching gestures |
| Release communications | [`UpdateHighlightsView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateHighlightsView.swift) | Update notification UI |
| Application removal | [`Uninstall/UninstallerView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Uninstall/UninstallerView.swift) | Guided uninstall wizard |
| Application removal | [`Uninstall/AppPickerView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Uninstall/AppPickerView.swift) | Target selection for uninstall |
| Visual consistency | [`Theme.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/URLCleaning.swift), permission checks in [`Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Permissions.swift), and hot-key management in [`SymbolicHotKeys.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/main.swift).

### What is the purpose of the NowPlayingAdapter module?

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