Buckets:
| # SovereignSurvivalKit Application Architecture | |
| > [!IMPORTANT] | |
| > **Version Control and State Tracking Rule**: | |
| > This repository exclusively uses **`lore`** for version control, state management, and documentation tracking. **Do NOT use `git`**. | |
| This document describes the structure, responsibilities, and dependencies of the primary application target in [`src/SovereignSurvivalKit/SovereignSurvivalKit`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit). | |
| --- | |
| ## 1. Overview and Purpose | |
| `SovereignSurvivalKit` is the central application bundle for macOS 27.0+ and iOS 27.0+. It links the modular framework packages into an integrated application managing encrypted data vaults, background server daemons, WireGuard mesh networking, and AI intelligence services. | |
| --- | |
| ## 2. Core Components and Source Files | |
| ```text | |
| src/SovereignSurvivalKit/SovereignSurvivalKit/ | |
| ├── SovereignSurvivalKitApp.swift # Main SwiftUI application entry point, scene routing & signal trapper | |
| ├── AppRootView.swift # Root window content view, environment injection & alert/importer coordination | |
| ├── MainContentView.swift # Primary workspace view with vault pills, canvas & quick-look panels | |
| ├── DocumentationRebuildManager.swift # Observable manager coordinating background DocGen rebuild workflows | |
| ├── PermissionTip.swift # TipKit inline prompt for adding vault items | |
| ├── ServicesCoordinator.swift # Daemon bootstrap, agent path & VPN configuration | |
| ├── SetupView.swift # Initial setup and onboarding view | |
| ├── SetupViewModel.swift # Setup state machine view model | |
| ├── VPNStatusView.swift # Live WireGuard mesh status & peer list view | |
| ├── SnippetTestHostView.swift # Host harness for testing SwiftUI snippet rendering | |
| ├── Info.plist # Application metadata & permission strings | |
| ├── SovereignSurvivalKit.entitlements # Sandbox, network & keychain entitlements | |
| ├── Assets.xcassets/ # App icons, colors & graphic assets | |
| ├── Intents/ # App Intent definitions linked to main app target | |
| ├── Template/ # Template configurations | |
| └── data/docs/SSK_Ledger_Vault/ # Active documentation ledger (docc_index, graph, DocC_Index) | |
| ``` | |
| ### Component Details | |
| #### [`SovereignSurvivalKitApp.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/SovereignSurvivalKitApp.swift) | |
| - **Application Entry Point**: Declares `@main struct SovereignSurvivalKitApp: App`. | |
| - **Signal Trapping**: Intercepts `SIGINT` and `SIGTERM` signals using `DispatchSource` signal handlers to cleanly flush metadata caches before process termination. | |
| - **Scene Coordination**: Configures `WindowGroup`, macOS `Settings`, and `MenuBarExtra` menu bar status items. | |
| #### [`AppRootView.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/AppRootView.swift) | |
| - **State Routing**: Evaluates `setupViewModel.state` to transition between `SetupView` and `MainContentView`. | |
| - **Modals & Importers**: Encapsulates `.fileImporter` handlers, error/save alerts, and `MXMetricSubscriber` telemetry registration. | |
| #### [`MainContentView.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/MainContentView.swift) | |
| - **Vault Workspace**: Displays active and connected vaults, `QuickLookBrowserView`, and `TopographicalCanvas`. | |
| - **Observation Consumer**: Subscribes to `AppModel` via `@Environment(AppModel.self)`. | |
| #### [`DocumentationRebuildManager.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/DocumentationRebuildManager.swift) | |
| - **DocGen State Machine**: `@Observable @MainActor` manager coordinating live DocGen commands via `XPCBridge`. | |
| #### [`PermissionTip.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/PermissionTip.swift) | |
| - **TipKit Definition**: Provides user onboarding guidance for adding items to vaults. | |
| #### [`ServicesCoordinator.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/ServicesCoordinator.swift) | |
| - **Vault Host Launch (`launchVaultHost`)**: Detects running status and launches `/Applications/SSKVaultHost.app` (or registered bundle `com.superbright.SSK.VaultHostLifecycle`) via `NSWorkspace` on main application launch. | |
| - **Daemon Lifecycle (`bootstrapDaemon`)**: Launches `SSKVaultHost` and registers `com.ssk.vaulthost.plist` via `SMAppService.agent` on macOS. | |
| - **Agent Path Stabilization (`configureStableAgentPath`)**: Creates a stable symlink to `SSK_StorageHost` in `~/Library/Application Support/SovereignSurvivalKit/Agent/SSK_Agent` for Xcode and external MCP clients. | |
| - **XPC Bridge (`connectToDaemon`)**: Connects to the background daemon via `XPCBridge.shared` to coordinate remote VPN negotiations. | |
| - **Encrypted Mesh Networking (`setupVPN`)**: Installs and updates system network configurations via `NETunnelProviderManager` and `WireGuardKit` for the `10.0.0.0/24` subnet. | |
| --- | |
| ## 3. Package and Framework Dependencies | |
| ### Internal Package Dependencies | |
| | Module | Integration Role | | |
| | :--- | :--- | | |
| | **`SSK_Abstractions`** | Domain entities, database schema bindings (`GRDB.swift`), and Accelerate LAPACK routines. | | |
| | **`SSK_Foundation`** | Multi-tier storage coordination (`StorageCoordinator`), XPC bridge, and SwiftSyntax parsing. | | |
| | **`SSK_Orchestrator`** | Intake pipeline (`IngestionCoordinator`), audio runtime, and biometric authorization. | | |
| | **`SSK_UI`** | SwiftUI layout views, `TopographicalCanvas`, and quick-look browser panels. | | |
| | **`SSK_Providers`** | LLM providers, zero-knowledge identity (`ZKIdentityService`), and HTTP/3 QUIC daemons. | | |
| | **`SSK_Hardware`** | Hardware telemetry, sensor feeds, and MLX audio stem processing. | | |
| | **`SSK_Demucs_MLX`** | HTDemucs neural music source separation on Apple Silicon MLX. | | |
| | **`SSK_Physics`** | Spatial math, amodal inversion, and reverse provenance deviation solvers. | | |
| | **`SSK_Intents`** | Programmatic intent routing and helper definitions. | | |
| ### System Framework Dependencies | |
| - **`SwiftUI` & `TipKit`**: Declarative UI hierarchy and in-app tips. | |
| - **`NetworkExtension` & `WireGuardKit`**: Encrypted packet tunneling and VPN configurations. | |
| - **`ServiceManagement`**: Launch agent management via `SMAppService`. | |
| - **`UniformTypeIdentifiers`**: File type identification and document import. | |
| --- | |
| ## 4. Architectural Position | |
| ```text | |
| +-------------------------------------------------------------------+ | |
| | SovereignSurvivalKit.app | | |
| | - SovereignSurvivalKitApp (@main) - ServicesCoordinator | | |
| | - SetupView & VPNStatusView - Data Ledger (SSK_Ledger_Vault)| | |
| +---------------------------------+---------------------------------+ | |
| │ | |
| ┌──────────────┬─────────┴───────┬──────────────┐ | |
| ▼ ▼ ▼ ▼ | |
| SSK_Abstractions SSK_Foundation SSK_Orchestrator SSK_UI | |
| ▼ ▼ ▼ ▼ | |
| SSK_Physics SSK_Hardware SSK_Providers SSK_Demucs_MLX | |
| ``` | |
Xet Storage Details
- Size:
- 7.55 kB
- Xet hash:
- 97bc8ce042a689fae7b009bb5aeb1b6e340759d7eb7865547fb58bae5179cdc3
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.