LOCALHOST1978/SovereignSurvivalKit/ARCHITECTURE.md

SovereignSurvivalKit Application Architecture

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.

---

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

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

• 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

• 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

• Vault Workspace: Displays active and connected vaults, QuickLookBrowserView, and TopographicalCanvas.
• Observation Consumer: Subscribes to AppModel via @Environment(AppModel.self).

DocumentationRebuildManager.swift

• DocGen State Machine: @Observable @MainActor manager coordinating live DocGen commands via XPCBridge.

PermissionTip.swift

• TipKit Definition: Provides user onboarding guidance for adding items to vaults.

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

+-------------------------------------------------------------------+
|                     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