LOCALHOST1978/SSKVaultHost/ARCHITECTURE.md

SSKVaultHost Architecture

Version Control and State Tracking Rule: This repository exclusively uses lore for version control, state management, and documentation tracking. Do NOT use git.

---

1. Overview and Purpose

SSKVaultHost is the resident macOS menu bar monitor and daemon lifecycle management application in the SovereignSurvivalKit architecture.

It performs three primary operational functions:

1. Live Menu Bar Monitoring: Runs as a resident macOS menu bar extra (MenuBarExtra) displaying real-time daemon reachability and SMAppService launch agent health status.
2. Operator Configuration & Registration: Validates operator-approved workspace and vault directories, storing them securely in DocGenHostConfigurationStore.
3. Launch Agent Lifecycle: Registers, starts, stops, and manages the background daemon via Apple ServiceManagement (SMAppService.agent) using the property list configuration com.ssk.vaulthost.plist.

---

2. Directory Layout and Components

src/SovereignSurvivalKit/SSKVaultHost/
├── ARCHITECTURE.md                  # Component architecture documentation
├── main.swift                       # App entry point, MenuBarExtra scene & headless CLI dispatcher
├── VaultHostMonitorModel.swift      # Observable state model tracking daemon connectivity and launch agent status
├── VaultHostMenuView.swift          # SwiftUI dropdown view for the macOS menu bar extra
└── com.ssk.vaulthost.plist          # Launchd agent configuration manifest

---

3. Key Responsibilities

1. Persistent Menu Bar Extra

• Presents a resident icon in the macOS menu bar reflecting real-time daemon reachability.
• Provides quick status indicators for SSK_StorageHost daemon connection and SMAppService agent status.
• Offers direct actions to refresh status, register/unregister daemon, and open the main application.

2. Launch Agent Management

• Uses SMAppService.agent(plistName:) to register and unregister the com.ssk.vaulthost daemon with the macOS background service management subsystem without requiring root privileges.
• Verifies and reports service state (.enabled, .requiresApproval, .notFound, .notRegistered).

3. Secure Path Authorization

• Reads SSK_DOCGEN_WORKSPACE and SSK_DOCGEN_VAULT environment variables when present.
• Standardizes paths, validates directory existence, and records approved roots via DocGenHostConfigurationStore.userApplicationSupport().

4. Headless Mode Dispatch

• Supports --setup-only / --headless CLI flags for automated package post-install scripts and provisioning workflows.

---

4. Dependencies

Framework Dependencies

• SwiftUI: Menu bar extra scene and UI interface.
• AppKit: Background accessory process policy configuration (.accessory).
• Observation: Modern @Observable state synchronization.
• ServiceManagement: SMAppService launch agent lifecycle management.
• Foundation: Environment inspection, file system validation, and process control.

Internal Module Dependencies

• SSK_Foundation: DocGenXPCCommandRouter, XPCCallerAuthorization, SSKFoundationConfiguration, XPCBridge.
• SSK_Providers: DocGenHostConfigurationStore.

---

5. Architectural Position

               macOS System Menu Bar
                         │
                         ▼
               SSKVaultHost (App)
                         │
        ┌────────────────┴────────────────┐
        ▼                                 ▼
SMAppService.agent               XPCBridge Health Probe
(com.ssk.vaulthost.plist)                 │
        │                                 ▼
        ▼                        SSK_StorageHost Daemon
 launchd (KeepAlive)            (com.ssk.vaulthost Mach XPC)