# Vorssaint-utils Project Structure: Complete Guide to the macOS Swift Package

> Explore the vorssaint-utils project structure a comprehensive guide to its macOS Swift package organization. Understand targets libraries and executables for efficient development.

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

---

**TLDR:** Vorssaint-utils is a macOS-only Swift package containing three SPM targets—two system libraries (`HIDEventSystem`, `VMStatisticsCompat`) and one executable (`Vorssaint`)—organized under `Sources/` with supporting tools, tests, and documentation at the repository root.

The **vorssaint-utils** repository delivers a single macOS utility application through a clean Swift Package Manager structure. Understanding this layout is essential for contributors, maintainers, and developers looking to extend or debug the codebase. This guide breaks down every directory, target, and key file based on the actual source implementation.

## SPM Package Architecture

The project defines its build configuration in **[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)** at the repository root. This file declares three distinct targets that work together to produce the final `Vorssaint` app.

| Target | Type | Purpose |
|--------|------|---------|
| **HIDEventSystem** | System library | Low-level HID event wrappers required by input handling services |
| **VMStatisticsCompat** | System library | Compatibility layer for macOS VM statistics APIs |
| **Vorssaint** | Executable | Main application containing UI, services, and entry point |

These targets follow SwiftPM conventions with source files located under `Sources/<TargetName>/`.

## Directory Structure Breakdown

### Sources Directory

The `Sources/` folder contains all compilable code organized by target.

```

Sources/
├── HIDEventSystem/          # System library: HID event abstractions

├── VMStatisticsCompat/      # System library: VM stats compatibility

└── Vorssaint/               # Executable: main application

    ├── main.swift           # Application entry point

    ├── UI/                  # Cocoa interface components

    │   └── WindowGestureControls.swift
    ├── Services/            # Feature implementations

    │   └── Audio/
    │       └── BoostLimiter.swift
    └── Core/                # Models, defaults, strings, feature catalog

```

The executable's **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** performs critical initialization: it registers user defaults, parses command-line arguments, and launches `NSApplication` for the Cocoa event loop.

### Supporting Directories

- **`.github/workflows/`** — GitHub Actions CI pipelines for automated builds and tests
- **`Docs/`** — Project documentation including [`README.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/README.md), [`CHANGELOG.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CHANGELOG.md), [`PRIVACY.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/PRIVACY.md), and [`PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/PERMISSIONS.md)
- **`Resources/`** — Localized strings (`.lproj` directories), `Info.plist`, and `Vorssaint.entitlements`
- **`Tests/`** — XCTest suite with [`MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MetricsTests.swift) for metric utility validation
- **`Tools/`** — Bash automation scripts:
  - [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) — compiles, signs, and packages the app
  - [`uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/uninstall.sh) — cleanup utility
  - [`make-dmg.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/make-dmg.sh) — distribution packaging

## Building and Running the Project

Compile the release binary using standard SwiftPM commands:

```bash

# Clone and enter the repository

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

# Build release executable

swift build -c release

```

Output appears at `./.build/release/Vorssaint`.

### Command-Line Modes

The executable supports several runtime flags defined in [`main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/main.swift):

```bash

# Launch full GUI application

./.build/release/Vorssaint

# Run self-test and exit

./.build/release/Vorssaint --selftest

# Dump hardware sensor data

./.build/release/Vorssaint --sensors

```

## Extending the Vorssaint-utils Project Structure

To add a new service feature:

1. Create a Swift file under `Sources/Vorssaint/Services/` (e.g., [`Sources/Vorssaint/Services/Display/NightMode.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Display/NightMode.swift))
2. Register the service in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift)
3. Rebuild with `swift build`

This pattern maintains the clean separation between system libraries and application logic that defines the vorssaint-utils architecture.

## Summary

- **Three SPM targets**: two system libraries plus one executable
- **Entry point**: [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) bootstraps Cocoa app lifecycle
- **Feature code**: organized under `Sources/Vorssaint/UI/`, `Services/`, and `Core/`
- **Build automation**: [`Tools/build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/build.sh) handles compilation, signing, and packaging
- **Single test file**: [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) for XCTest validation

## Frequently Asked Questions

### What build system does vorssaint-utils use?

The project uses **Swift Package Manager** defined in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) at the repository root. No Xcode project file is required; builds use `swift build` commands.

### Where is the application entry point located?

The main entry point is **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)**, which initializes defaults, processes command-line flags like `--selftest` and `--sensors`, and starts the `NSApplication` run loop.

### How are system-level dependencies handled?

Two dedicated system library targets—`HIDEventSystem` and `VMStatisticsCompat`—wrap low-level macOS APIs. These isolate platform-specific code from the main application logic.

### Can I build vorssaint-utils without Xcode?

Yes. The repository includes **[`Tools/build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/build.sh)**, a Bash script that compiles the project using `swift build`, creates the app icon, signs the bundle, and optionally installs it. CI pipelines in `.github/workflows/` also build without Xcode interaction.