Architecture

​

Project structure

HopTab/
├── App/              # Application lifecycle and state
├── Models/           # Data structures and persistence
├── Services/         # Core functionality (hotkeys, switching, permissions)
└── Views/            # SwiftUI UI components

​

App layer

• HopTabApp.swift - SwiftUI app entry point with MenuBarExtra and Settings scenes
• AppDelegate.swift - Handles launch, permission checks, and hotkey initialization
• AppState.swift - Central @ObservableObject that coordinates all services and publishes state changes to views

@main
struct HopTabApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) private var delegate

    var body: some Scene {
        MenuBarExtra("HopTab", systemImage: "arrow.2.squarepath") {
            MenuBarView()
                .environmentObject(delegate.appState)
        }

        Settings {
            SettingsView()
                .environmentObject(delegate.appState)
        }
    }
}

• Pinned apps store (PinnedAppsStore)
• Hotkey service (HotkeyService)
• Overlay window controllers
• Running apps list
• Shortcut configuration
• Profile switching logic
• Desktop assignment via Space tracking

​

Models layer

• PinnedApp - Represents a pinned application with bundle ID, display name, and sort order
• Profile - Named collection of pinned apps (e.g., “Coding”, “Design”)
• PinnedAppsStore - Manages profiles, active profile, and persistence to UserDefaults
• ShortcutConfig - Configurable keyboard shortcut presets and custom shortcuts
• KeyCodeMapping - Maps key codes to human-readable names

struct PinnedApp: Codable, Identifiable, Equatable, Hashable {
    let bundleIdentifier: String
    let displayName: String
    var sortOrder: Int

    var id: String { bundleIdentifier }

    // Computed properties
    var icon: NSImage { ... }
    var isRunning: Bool { ... }
    var runningApplication: NSRunningApplication? { ... }
    var applicationURL: URL? { ... }
}

​

Services layer

• HotkeyService - Global keyboard event monitoring via CGEvent tap
• AppSwitcherService - App activation using NSRunningApplication and AXUIElement
• SpaceService - Desktop (Space) tracking via private CGS APIs
• PermissionsService - Accessibility permission checks

​

Views layer

• MenuBarView - Menu bar dropdown with profile selector and settings access
• SettingsView - Multi-tab settings window (Pinned Apps, Profiles, Shortcut)
• OverlayPanel - Non-activating NSPanel for the app switcher overlay
• OverlayView - SwiftUI view showing pinned apps with vibrancy blur
• ProfileOverlayView - Profile switcher overlay
• AppIconView - App icon rendering with running indicator
• ShortcutRecorderView - Custom shortcut key recorder

​

Core architectural decisions

​

SwiftUI + AppKit hybrid

• SwiftUI for declarative UI (settings, menu bar, overlay content)
• AppKit for system-level functionality (event taps, window management, accessibility)

​

State management

@MainActor
final class AppState: ObservableObject {
    let store = PinnedAppsStore()
    let permissions = PermissionsService()

    private let hotkeyService = HotkeyService()
    private let overlayController = OverlayWindowController()
    private let profileOverlayController = ProfileOverlayWindowController()

    @Published private(set) var selectedIndex: Int = 0
    @Published private(set) var isSwitcherVisible: Bool = false
    @Published var runningApps: [NSRunningApplication] = []
    // ...
}

private func setupHotkeyCallbacks() {
    hotkeyService.onSwitcherActivated = { [weak self] in
        self?.showSwitcher()
    }

    hotkeyService.onCycleForward = { [weak self] in
        self?.cycleForward()
    }

    hotkeyService.onSwitcherDismissed = { [weak self] in
        self?.dismissAndActivate()
    }
    // ...
}

​

Persistence

• Pinned apps (per profile)
• Profiles and active profile
• Desktop-to-profile assignments
• Shortcut configuration

​

No sandboxing

​

Accessibility dependency

1. Event tap creation - CGEvent.tapCreate(.cgSessionEventTap, ...) requires it
2. Window raising - AXUIElementPerformAction(window, kAXRaiseAction) forces windows to the front

​

Data flow

1. User presses shortcut → HotkeyService detects via event tap
2. HotkeyService callback → AppState.showSwitcher() called
3. AppState reads data → Gets pinned apps from PinnedAppsStore
4. AppState shows overlay → OverlayWindowController.show() displays UI
5. User cycles apps → HotkeyService detects Tab presses → AppState updates selection
6. User releases modifier → HotkeyService callback → AppState.dismissAndActivate()
7. AppState activates app → AppSwitcherService.activate() brings app to front
8. Service uses AX API → AXUIElementPerformAction raises windows

​

Threading model

@MainActor
final class AppState: ObservableObject { ... }

@MainActor
final class AppDelegate: NSObject, NSApplicationDelegate { ... }