# Project Structure of vorssaint-utils: A Complete Guide to the macOS Swift Architecture > Explore the vorssaint-utils project structure, a Swift Package Manager layout with system libraries and an executable. Understand its UI components, services, and core logic organization. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: architecture - Published: 2026-09-13 --- **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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) which implements macOS window snapping and resizing interactions. **`Sources/Vorssaint/Services/`** Houses feature implementations such as audio processing (including [`Audio/BoostLimiter.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)** – Compiles the release binary, generates app icons, handles code signing with proper entitlements, and constructs the final `.app` bundle - **[`uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/uninstall.sh)** – Removes installed components and cleans build artifacts from the system - **[`make-dmg.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](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), [`PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/PERMISSIONS.md), `LICENSE`, [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md), [`SECURITY.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/SECURITY.md), and [`TRADEMARKS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/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: ```bash # 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/main.swift): ```bash # 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/NightModeSupport.swift)) 2. Register the capability in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) handles initialization before launching the Cocoa event loop - Testing infrastructure centers on [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) for compilation and code signing, [`uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/uninstall.sh) for cleanup, and [`make-dmg.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/make-dmg.sh) for creating distributable disk images. These scripts handle the complete pipeline from Swift compilation to notarized macOS app bundles.