Project Structure of vorssaint-utils: A Complete Guide to the macOS Swift Architecture

The vorssaint-utils repository follows a Swift Package Manager layout with three distinct targets—two system libraries (HIDEventSystem, VMStatisticsCompat) and one executable (Vorssaint)—organized under Sources/ with dedicated directories for UI components, services, and core logic.

The vorssaint-utils project is a macOS-only Swift utility that provides system-level functionality through a modular, maintainable architecture. As a Swift Package Manager (SPM) package, it separates low-level hardware integrations from high-level application features. Understanding the project structure of vorssaint-utils is essential for contributors extending hardware monitoring capabilities or debugging system-level interactions.

Top-Level Directory Layout

The repository root organizes code, documentation, and automation into logical groups:

• Sources/ – Contains all Swift source code organized by SPM target
• Tests/ – XCTest suites for validating core functionality
• Tools/ – Bash automation scripts for building and packaging
• Resources/ – Localized strings, entitlements, and plist configuration files
• Docs/ – Markdown documentation and supporting assets
• .github/workflows/ – CI/CD pipelines for automated validation

Swift Package Manager Targets

The Package.swift file defines the package manifest and three distinct targets that separate system wrappers from application logic.

HIDEventSystem (System Library)

Located at Sources/HIDEventSystem/, this target provides low-level HID event wrappers required by hardware interaction services. It bridges macOS Human Interface Device APIs with the application's higher-level abstractions, handling raw input events from system peripherals.

VMStatisticsCompat (System Library)

Found at Sources/VMStatisticsCompat/, this compatibility layer abstracts macOS VM statistics across different OS versions. It provides consistent memory and process statistics APIs regardless of underlying macOS kernel changes, ensuring reliable hardware monitoring.

Vorssaint (Executable)

The primary application target resides in Sources/Vorssaint/ and houses the full Cocoa app implementation. The entry point is Sources/Vorssaint/main.swift, which bootstraps the application by registering user defaults, parsing command-line arguments, and launching the NSApplication main loop.

This target organizes its internal components into three functional subdirectories:

Sources/Vorssaint/UI/
Contains window management and interface controls, including WindowGestureControls.swift which implements macOS window snapping and resizing interactions.

Sources/Vorssaint/Services/
Houses feature implementations such as audio processing (including Audio/BoostLimiter.swift for per-app volume limiting) and hardware monitoring services.

Sources/Vorssaint/Core/
Stores foundational models, string constants, user defaults management, and FeatureCatalog.swift—the registry that coordinates available application capabilities.

Build System and Automation

The Tools/ directory contains bash scripts that automate the entire distribution pipeline:

• build.sh – Compiles the release binary, generates app icons, handles code signing with proper entitlements, and constructs the final .app bundle
• uninstall.sh – Removes installed components and cleans build artifacts from the system
• make-dmg.sh – Packages the signed application into a distributable disk image with proper volume formatting

CI/CD configuration lives in .github/workflows/, where GitHub Actions workflows validate builds, run test suites, and check code signing requirements on every push.

Testing Infrastructure

Quality assurance relies on XCTest frameworks located in the Tests/ directory. The primary suite, Tests/MetricsTests.swift, validates hardware metric calculations and system monitoring utilities. These tests integrate with the CI pipeline to prevent regressions in sensor data processing.

Documentation and Resources

Documentation follows standard open-source conventions:

• Repository root: README.md, CHANGELOG.md, PRIVACY.md, PERMISSIONS.md, LICENSE, CONTRIBUTING.md, SECURITY.md, and TRADEMARKS.md
• Docs/assets/ – Screenshots and diagrams supporting user documentation
• Resources/*.lproj/ – Localized string tables for internationalization
• Resources/Vorssaint.entitlements – Sandboxing permissions and capability declarations required for macOS distribution

Building and Running the Project

To compile the project locally, ensure Xcode Command Line Tools are installed and execute:

# Clone the repository

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

# Build the release executable

swift build -c release

The compiled binary appears at ./.build/release/Vorssaint. The executable supports several command-line modes as implemented in main.swift:

# Launch the full GUI application

./.build/release/Vorssaint

# Run internal diagnostics and exit

./.build/release/Vorssaint --selftest

# Display CPU, GPU, and temperature sensor data

./.build/release/Vorssaint --sensors

Extending the Codebase

When adding new features to the Vorssaint app, follow the established modular pattern:

1. Create service implementations in Sources/Vorssaint/Services/ (e.g., NightModeSupport.swift)
2. Register the capability in Sources/Vorssaint/Core/FeatureCatalog.swift to make it discoverable
3. Add UI components to Sources/Vorssaint/UI/ if user interaction is required
4. Rebuild using swift build to incorporate the new module

Summary

• The project structure of vorssaint-utils uses Swift Package Manager conventions with three targets defined in Package.swift
• Two system library targets (HIDEventSystem and VMStatisticsCompat) provide low-level macOS hardware integrations
• The main Vorssaint executable organizes code into UI/, Services/, and Core/ subdirectories for maintainability
• Build automation resides in Tools/ scripts, while CI configuration lives in .github/workflows/
• The application entry point at Sources/Vorssaint/main.swift handles initialization before launching the Cocoa event loop
• Testing infrastructure centers on Tests/MetricsTests.swift using standard XCTest frameworks

Frequently Asked Questions

Where is the main entry point in vorssaint-utils?

The application entry point is located at Sources/Vorssaint/main.swift. This file initializes user defaults, parses command-line flags (such as --selftest and --sensors), and launches the NSApplication main loop for the Cocoa interface.

What are the HIDEventSystem and VMStatisticsCompat targets?

These are system library targets defined in Package.swift. HIDEventSystem provides wrappers for macOS Human Interface Device events, while VMStatisticsCompat offers a compatibility layer for virtual memory statistics across different macOS versions. Both reside under Sources/ and support the main executable's hardware interaction capabilities.

How do I add a new feature to the Vorssaint app?

Create a new Swift file in the appropriate subdirectory under Sources/Vorssaint/—typically Services/ for backend logic or UI/ for interface components. Then register the feature in Sources/Vorssaint/Core/FeatureCatalog.swift and rebuild using swift build.

What build tools are available for packaging the application?

The Tools/ directory contains bash scripts including build.sh for compilation and code signing, uninstall.sh for cleanup, and make-dmg.sh for creating distributable disk images. These scripts handle the complete pipeline from Swift compilation to notarized macOS app bundles.

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