LOCALHOST1978/Modules/SSK_UI/ARCHITECTURE.md

SSK_UI 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

SSK_UI is the presentation layer module within the SovereignSurvivalKit architecture. It provides platform-native SwiftUI views, interactive canvas layouts, multi-media asset preview panels, and custom widgets for macOS 27.0+ and iOS 27.0+.

The module isolates visual components and layout logic from underlying storage, network protocols, and hardware processing engines.

---

2. Package Specifications and Dependencies

Defined in Package.swift:

• Target Name: SSK_UI
• Swift Tools Version: 6.4
• Supported Platforms: macOS 27.0+, iOS 27.0+
• Internal Package Dependencies:
  • SSK_Abstractions — Shared domain entities and UI widget models.
  • SSK_Foundation — Storage coordinator, finder models, and performance tracing (MXPerformanceTracer).
  • SSK_Providers — Concrete cryptographic routines and identity services.
  • SSK_Orchestrator — App state models (AppModel) and intake runtime controllers.
  • SSK_Hardware — Audio telemetry and stem models.
• System Frameworks:
  • SwiftUI, Charts, ImagePlayground, TipKit, UniformTypeIdentifiers, QuickLook.

---

3. Component Architecture and Source Layout

Sources/SSK_UI/
├── AudioIngestionWidgets.swift      # Swift Charts audio waveform & stem separation snippet UI
├── CommerceSearchView.swift        # Offline UCP merchant & product catalog search view
├── ModelManagementView.swift       # On-device ML model manager, download progress & memory stats
├── PermissionStatusView.swift      # Full Disk Access and Automation permission status view
├── PinEntryView.swift              # Cryptographic PIN entry dialog for high-security actions
├── QuickLookBrowserView.swift      # Multi-MIME asset preview panel with interactive playheads
├── TimeCapsuleNodeView.swift       # Temporal node visualizer with 12-bin chromagram color bars
├── TopographicalCanvas.swift       # Dynamic canvas container for asset browsing & navigation
├── VaultImageGeneratorView.swift   # Apple ImagePlayground sheet integration for vault icons
└── UIConfiguration.swift           # Visual theme tokens, layout geometry constants & defaults

---

4. Subsystem Breakdown

1. AudioIngestionWidgets.swift

• Implements AudioIngestionSnippetView using Apple Charts and SwiftUI.
• Renders audio waveform energy profiles, isolated stem balances (Vocals, Drums, Bass, Other), processing progress indicators, and status badges for Siri and Shortcuts modal overlays.

2. CommerceSearchView.swift

• Provides an offline-first Universal Commerce Protocol (UCP) search interface.
• Executes local product and merchant catalog queries via AskUCPClient and converts results into managed assets in AppModel.

3. ModelManagementView.swift

• Manages on-device ML model downloads (HTDemucs, Foundation Models).
• Displays model file sizes, download progress, checksum verification status, and active neural compute engine metrics.

4. PinEntryView.swift

• Secure 4-digit PIN entry dialog used to confirm critical operations (such as cryptographic emergency erasure or session abort via BilateralSettlement).

5. QuickLookBrowserView.swift

• Multi-format asset preview panel supporting audio waveforms (AudioPreviewView), frequency spectrums, text documents (TextPreviewView), and video assets.
• Integrates MXPerformanceTracer to ensure 60 fps rendering during interactive scrub operations.

6. TopographicalCanvas.swift & TimeCapsuleNodeView.swift

• Dynamic canvas layout displaying sovereign assets (KassetItem).
• Renders process algebra transitions (CCSOperator), cryptographic hashes, and 12-bin chromagram spectrum bars.

---

5. Architectural Position

                        SSK_Abstractions
                               ▲
                               │
+------------------------------┴------------------------------------+
|                              SSK_UI                               |
|  - AudioIngestionSnippetView       - TopographicalCanvas          |
|  - CommerceSearchView (UCP)        - QuickLookBrowserView         |
|  - ModelManagementView             - PinEntryView                 |
+-------------------------------------------------------------------+
         ▲              ▲                 ▲                 ▲
         │              │                 │                 │
   SSK_Foundation  SSK_Hardware     SSK_Providers    SSK_Orchestrator