Help Home / Under the Hood

Under the Hood

A technical look at SwiftMiner's internal architecture. Explore how we utilize native Swift concurrency, local SQLite engines, secure macOS keychains, and socket networking to build a high-performance desktop application.

SwiftMiner is engineered from the ground up as a native macOS application. Instead of relying on bloated browser frameworks or resource-intensive electron wrappers, it is built directly on Apple's developer frameworks to run in the background with negligible memory and CPU footprints.

System Architecture

The application is split into three main modules to maintain strict separation of concerns:

  • App UI (SwiftUI): Responsible for the native macOS layouts, including the multi-miner overview cards, real-time log consoles, and account settings panels.
  • SwiftMinerCore: The core daemon engine that manages token lifecycle operations, active drop tracking, automatic claiming intervals, and database synchronization.
  • SwiftMinerService: Houses the embedded HTTP web dashboard daemon that parses incoming local LAN connections and enforces Twitch OAuth token validations.

Swift Concurrency Model

SwiftMiner relies heavily on modern Swift Concurrency (async/await, Actors, and Structured Concurrency) to orchestrate dozens of background activities simultaneously without freezing the user interface.

  • Actors for Thread Safety: To prevent data races, core subsystems like MinerEngine, KeychainTokenStore, and HTTPAPIServer are defined as Swift actors. This guarantees that all access to their internal state is isolated and processed sequentially across threads.
  • Structured Concurrency: The MinerManager supervises individual account miners using structured tasks. Each miner operates on its own task loop, executing polling cycles, stream switching, and claiming operations independently. If an account is removed or paused, its specific task tree is canceled cleanly.
  • Non-blocking UI: State changes (such as progress bars updating or new logs arriving) are funneled from background threads back to the Main Actor (UI thread) using reactive publishers. This ensures the SwiftUI layout re-renders smoothly.

API Clients & WebSockets

SwiftMiner connects directly to Twitch servers using optimized network clients with zero intermediary relays.

  • REST & GraphQL client: The core TwitchAPIClient interfaces with Twitch Helix API endpoints and GQL endpoints. Request batches are managed via URLSession utilizing HTTP/2 connection pooling to keep network overhead low.
  • WebSocket PubSub: To avoid aggressive API rate limits and retrieve progress changes instantly, PubSubClient establishes a persistent connection to Twitch's WebSocket-based PubSub system. This allows the app to listen for real-time claim triggers and progression events the moment they are recorded.
  • User-Agent Matching: To prevent API requests from being flagged or rejected by Twitch, the client requests generate custom headers matching typical desktop Safari/Chrome browsers.

SQLite Caching

To avoid hammering Twitch's servers on startup and keep history local, SwiftMiner integrates a local database layer.

  • Engine Details: SwiftMiner uses a local, lightweight SQLite instance managed via the SQLiteManager. It maintains tables for campaign details, active channels, claim records, and session data for the Web Dashboard.
  • Automatic Purging: Old campaign listings, telemetry data, and expired local Web Dashboard sessions are regularly purged automatically to prevent database bloat.

macOS System Integration

SwiftMiner relies on Apple's security APIs to secure your Twitch account details.

  • Keychain Services: Your Twitch OAuth tokens and client credentials are never saved in plain text database tables. They are written to the macOS System Keychain using Apple's Keychain Services API, providing hardware-backed security.
  • No Cloud Relays: Unlike cloud-based services, SwiftMiner runs entirely on your Mac. Your private Twitch credentials never leave your machine and are only sent directly to Twitch APIs.

Custom Web Daemon

The Web Dashboard server is a masterpiece of zero-dependency native engineering.

  • Network.framework: Instead of pulling in massive server-side frameworks (like Vapor, Kitura, or Node.js), SwiftMiner implements HTTPAPIServer directly on top of Apple's low-level Network.framework. It acts as a lightweight TCP socket listener.
  • Performance: The server runs directly in the background with a memory overhead of less than 5 MB. It parses standard HTTP/1.1 headers, decodes query parameters, and routes them to handler closures asynchronously.