LOCALHOST1978/Modules/SSK_Foundation/ARCHITECTURE.md

SSK_Foundation Module 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_Foundation is the core infrastructure layer of the SovereignSurvivalKit application ecosystem. It provides low-level system services, multi-tier storage management, encrypted vault lifecycle, cross-process communication (XPC), peer discovery, file system abstractions, audio artifact storage, and SwiftSyntax AST parsing.

SSK_Foundation provides thread-safe, actor-isolated services to higher-level modules (SSK_Hardware, SSK_Providers, SSK_Orchestrator, and SSK_UI).

---

2. Package Dependencies and Exports

As defined in Package.swift:

• Target Name: SSK_Foundation
• Swift Tools Version: 6.4
• Supported Platforms: macOS 27.0+, iOS 27.0+
• Internal Dependencies:
  • SSK_Abstractions — Core protocols, interfaces, and domain data types.
• External Dependencies:
  • swift-syntax (603.0.2+) — SwiftSyntax and SwiftParser for AST source code analysis.
  • swift-sdk (main branch) — Model Context Protocol (MCP) integration.

---

3. Subsystems and Architecture Layout

The source files in Sources/SSK_Foundation/ are organized into functional subsystems:

Sources/SSK_Foundation/
├── Storage & Persistence/
│   ├── StorageCoordinator.swift       # Unified coordinator for DB, cache, vault & memory
│   ├── DatabaseManager.swift          # Thread-safe SQLite/GRDB database engine with FTS5
│   ├── MemoryStore.swift              # Actor-isolated in-memory cache with TTL expiration
│   ├── FileCacheManager.swift         # Local disk binary caching engine
│   ├── AudioArtifactStore.swift       # Storage manager for audio stems & analysis artifacts
│   ├── TelemetryStore.swift           # Persistent storage for runtime metrics & telemetry
│   └── ICloudDriveProvider.swift      # iCloud Drive document sync provider
│
├── Security & Vault Lifecycle/
│   ├── EncryptedFileVaultManager.swift # AES-GCM encrypted file storage via CryptoKit
│   ├── SparsebundleManager.swift      # macOS encrypted disk image (.sparsebundle) lifecycle
│   ├── VaultLifecycleController.swift # Vault creation, mounting, verification & teardown
│   ├── VaultLifecycleModels.swift     # Data models for vault states & operation results
│   ├── VaultKeyManager.swift          # Secure Keychain storage for master vault keys
│   ├── VPNKeyManager.swift            # Keychain storage for WireGuard/IKEv2 credentials
│   └── KeychainUtilities/             # Low-level Apple Keychain helper utilities
│
├── Cross-Process Communication & Authorization/
│   ├── XPCBridge.swift                # Bidirectional XPC bridge between app and daemons
│   ├── XPCCallerAuthorization.swift   # Code signature & audit token validation for XPC callers
│   ├── DocGenXPCCommandRouter.swift   # Routes DocGen commands across the Mach XPC service
│   ├── DocGenProcessWorkerExecutor.swift # Spawns and supervises isolated DocGen worker CLI
│   └── IntentDonationQueue.swift      # Thread-safe queue for Siri/Shortcuts intent donations
│
├── File System & Finder Integration/
│   ├── FinderCore.swift               # POSIX and Foundation file system operations
│   ├── FinderModels.swift             # Structural models representing files, folders & trees
│   ├── FileNode.swift                 # Tree node data structure for directory hierarchies
│   ├── FinderOwnership.swift          # POSIX permission checks and ownership verification
│   ├── FinderPersistence.swift        # Directory scan persistence and serialized caches
│   ├── FinderCacheManager.swift       # In-memory caching layer for fast file lookups
│   └── LoreIgnore.swift               # Pattern matcher for .loreignore rule evaluation
│
├── Mesh Networking & Peer Discovery/
│   ├── SpatialDiscoveryService.swift  # AWDL/Bonjour local peer discovery & signal tracking
│   ├── PeerRegistry.swift             # Actor-isolated registry for approved mesh peer nodes
│   └── AskUCPClient.swift             # Client for querying Universal Commerce Protocol nodes
│
├── Code Analysis & AST Parsing/
│   ├── Instrumenter.swift             # SwiftSyntax engine for AST traversal and instrumentation
│   ├── SchemaValidator.swift          # JSON Schema and structural payload validator
│   └── SemanticGraphEncoder.swift     # Serializes AST structures into semantic graph vectors
│
├── Observability & Telemetry/
│   ├── HardwareTelemetryBridge.swift  # Bridge for thermal, memory, and hardware telemetry
│   ├── AudioTelemetryProjection.swift # Multi-dimensional projection of audio telemetry
│   ├── AudioSignatureService.swift    # Feature extraction and acoustic fingerprint helper
│   ├── MXPerformanceTracer.swift      # Latency measurement and performance hotspot tracer
│   └── MXMetricSubscriber.swift       # Apple MetricKit subscriber for CPU, GPU and memory
│
└── Configuration & Workflow/
    ├── FoundationConfiguration.swift  # Global runtime configuration settings for Foundation
    ├── AppGroupConstants.swift        # App Group container identifier constants
    └── SetupWorkflow.swift            # Initial setup and bootstrapping orchestration

---

4. Key Subsystem Responsibilities

1. Multi-Tier Storage Coordination

StorageCoordinator provides a unified facade across multiple storage tiers:

• Tier 0: MemoryStore for fast in-memory key-value caching.
• Tier 1: DatabaseManager for structured records and full-text search via GRDB.
• Tier 2: AudioArtifactStore and FileCacheManager for binary disk artifacts.
• Tier 3: EncryptedFileVaultManager and SparsebundleManager for encrypted data at rest.

2. XPC Security and DocGen Isolation

• XPCCallerAuthorization validates client audit tokens, team identifiers, and entitlements before processing commands.
• DocGenProcessWorkerExecutor executes SSK_DocGen in an isolated subprocess with descriptor-relative path access.

3. File System Governance with LoreIgnore

• LoreIgnore evaluates .loreignore rule files to exclude non-tracked files from scans, replacing Git-based ignore mechanisms.

---

5. Architectural Position

                           SSK_Abstractions
                                  ▲
                                  │
+---------------------------------+---------------------------------+
|                         SSK_Foundation                            |
|  - StorageCoordinator             - SparsebundleManager           |
|  - XPCBridge & Authorization      - DocGenProcessWorkerExecutor   |
|  - SwiftSyntax Instrumenter       - SpatialDiscoveryService       |
|  - LoreIgnore Pattern Matching    - HardwareTelemetryBridge       |
+---------------------------------+---------------------------------+
                                  ▲
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
   SSK_Hardware             SSK_Providers            SSK_Orchestrator