stephendev0/stikdebug-legacy

1. What this repo is

- StikDebug is an iOS-first, on-device utility app built in Swift/SwiftUI.

- Its core purpose is to connect to the current device, inspect it, and perform debug-oriented actions such as JIT enabling, process inspection, app launching, console logging, and location simulation.

- The architecture is centered around local device control rather than any backend service.

2. Top-level app composition

- The app entry point is StikDebugApp.swift, with AppBootstrapper.swift and AppFeature.swift acting as the startup/coordinator layer.

- The main user experience is tab-based (MainTabView.swift) and is split into feature screens such as Home, Installed Apps, Console Logs, Tools, Settings, Profile, and Process Inspector.

- This suggests a feature-oriented UI with shared app state/services feeding multiple tabs.

3. Device connectivity is the core subsystem

- The most important boundary in the repo is between the Swift app and the device-level native bridge.

- StikDebug/idevice contains a bundled C library interface (libidevice_ffi.a, idevice.h, module.modulemap) used to talk to Apple device services.

- Higher-level Swift wrappers (IdeviceFFIBridge.swift, DeviceConnectionContext.swift, DeviceInfoManager.swift, JITEnableContext.swift) abstract the raw FFI into app-safe workflows.

4. Pairing, tunneling, and DDI mounting

- The app relies on a pairing file (PairingFileStore.swift) to authenticate against the device.

- TunnelManager.swift and the README’s loopback VPN requirement indicate the app depends on a local tunnel/VPN path to reach device services on iOS 17.4+.

- DeveloperDiskImageService.swift and mountDDI.swift handle Developer Disk Image-related setup, which is typically required for deeper device interaction and JIT-related capabilities.

- MountingProgress.swift and related contexts imply this setup is asynchronous and surfaced to the UI as progress state.

5. JIT enablement workflow

- The flagship action is enabling JIT for sideloaded apps.

- The flow is: select a paired device, establish the tunnel/connection, mount required disk image/services if needed, then enable JIT for a chosen installed app.

- InstalledAppsViewModel.swift, InstalledAppListItem.swift, and InstalledAppRows.swift drive the app-selection UI, while JITEnableContext.swift likely coordinates the activation sequence.

6. Installed apps and app metadata

- The Installed Apps feature is its own subsystem, not just a UI list.

- AppIconRepository.swift and AppStoreIconFetcher.swift indicate the app enriches local installed-app records with icons/metadata.

- The app can launch installed apps and appears to track app expiry/profile-related state, which matches the README’s “App Expiry” feature.

7. Console, logs, and process inspection

- ConsoleLogsView.swift, SystemLogStream.swift, and LogManager.swift provide live log streaming from both apps and the system.

- ProcessInspectorView.swift suggests the app can enumerate running processes, inspect them, and potentially terminate them.

- These are device-sourced streams/actions, so the data flow is from the device bridge into log/process views rather than from local persistence.

8. Script management and JavaScript support

- JSSupport is a separate subsystem for managing and running JS-based automation.

- ScriptStore.swift, ScriptListView.swift, ScriptEditorView.swift, and RunJSView.swift provide script lifecycle management and execution UI.

- AutoScriptAssignments.swift suggests scripts can be bound to specific apps or conditions, which is useful for JIT automation flows.

- The bundled scripts in Scripts/ (Geode.js, UTM-Dolphin.js, maciOS.js, universal.js) show that the system ships with predefined automation recipes.

9. Device utility services

- Several services support the app’s “keep the device usable while debugging” behavior:

- BackgroundAudioManager.swift

- BackgroundLocationManager.swift

- DebugKeepAliveLease.swift

- AccessibilityAnnouncer.swift, Haptics.swift, and AlertPresenter.swift for user feedback

- MapSelectionView.swift and the README’s “Location Simulator” feature indicate a location spoofing/simulation flow backed by those services.

10. Shared support layer

- The Support/ folder contains cross-cutting helpers and app infrastructure: file lookup, document picker copying workaround, notification names, user defaults keys, localization, and codable app storage helpers.

- ScriptStore, PairingFileStore, and related types likely provide the local persistence boundary for pairing files, scripts, and configuration state.

- This layer keeps storage/UI/device-bridge concerns separated from the feature screens.

11. Feature and view organization

- The Features/ and Views/ folders show a modular split between domain logic and screens.

- HomeView, InstalledAppsListView, ToolsView, SettingsView, ProfileView, and MapSelectionView are the primary user-facing surfaces.

- HomeExternalAction.swift suggests the home screen can react to external triggers or system events.

12. Platform and build boundaries

- This is an Xcode-based iOS app (StikDebug.xcodeproj) with SwiftPM integration and explicit entitlements (StikDebug.entitlements).

- The project includes tests (StikDebugTests, StikDebugUITests) and a DebugWidgetExtension scheme, implying some auxiliary target support.

- Assets, localization, and Info.plist are standard app packaging pieces, but the key architectural constraint is device-level capability access through signing/entitlements.

13. Automation and release infrastructure

- GitHub Actions workflows (build_ipa.yml, updatesource.yml) indicate the repo has CI for building distributable IPAs and syncing/updating source-related outputs.

- The README’s distribution paths (AltSource/direct IPA) reinforce that this project is meant to be built and shipped as an installable iOS app, not deployed as a server.

14. Overall architecture in one sentence

- StikDebug is a feature-based SwiftUI iOS app whose UI tabs drive a device-control backend built on an idevice FFI bridge, with supporting services for pairing, tunneling, DDI mounting, JIT activation, logging, script automation, and device utility features.