keys-for-all/docs/PORTABLE_KEY_SYSTEM.md

Portable Key System: Multi-App Feature Marketplace

Overview

A portable, reusable system for selling and spending keys across different apps. Each app can define its own feature costs while sharing the same underlying key economy, purchase infrastructure, and community features.

Core Architecture

Universal Components (Portable)

• Key Purchase System: Buy key packs across 5 platforms (Apple, Google, Stripe, PayPal, Steam)
• Key Storage & Sync: Secure wallet with cross-device synchronization
• Community Features: Donations, sharing, community pool
• Web Portal: Account management, purchasing, gifting

App-Specific Components (Configurable)

• Feature Definitions: Each app defines what features cost how many keys
• Feature Gating: App-specific UI for locked features and key spending
• Feature Unlocking: App handles the actual feature activation

Key Economy Model

Base Economics

• 1 Key = $3.00 (universal across all apps)
• Key Packs: 1-500 keys with bulk discounts and community donations
• Multi-Platform: Same keys work across iOS, Android, Web, Steam, etc.

App-Specific Feature Pricing

Each app defines its own feature costs:

{
  "app": "VoiceUwu",
  "features": {
    "advanced_monitors": { "cost": 2, "name": "Advanced Voice Monitors" },
    "circle_trail_viz": { "cost": 3, "name": "Circle Trail Visualization" },
    "multi_monitor": { "cost": 2, "name": "Multi-Monitor Dashboard" },
    "export_data": { "cost": 1, "name": "Data Export" },
    "haptic_feedback": { "cost": 1, "name": "Enhanced Haptics" },
    "particle_system": { "cost": 3, "name": "Particle Visualization" }
  }
}

{
  "app": "OtherApp",
  "features": {
    "premium_theme": { "cost": 1, "name": "Premium Themes" },
    "advanced_analytics": { "cost": 4, "name": "Advanced Analytics" },
    "api_access": { "cost": 5, "name": "API Access" }
  }
}

System Components

1. Portable Key Infrastructure

VUKeyWallet (Cross-App)

protocol VUKeyWalletProtocol {
    // Balance management
    func getKeyBalance() async -> Int
    func spendKeys(_ amount: Int, for feature: String, in app: String) async throws
    func addKeys(_ amount: Int, from purchase: Purchase) async throws
    
    // Cross-device sync
    func syncWallet() async throws
    func getTransactionHistory() async -> [KeyTransaction]
    
    // Community features
    func donateKeys(_ amount: Int) async throws
    func shareKeys(_ amount: Int, with email: String) async throws
}

VUKeyPurchaseManager (Cross-App)

protocol VUKeyPurchaseManagerProtocol {
    // Multi-platform purchasing
    func purchaseKeyPack(_ pack: KeyPack, via platform: Platform) async throws
    func getAvailablePacks(for platform: Platform) async -> [KeyPack]
    func restorePurchases() async throws
}

enum Platform {
    case apple, google, stripe, paypal, steam
}

2. App-Specific Integration

VUFeatureGateManager (Per-App)

protocol VUFeatureGateManagerProtocol {
    // Feature management
    func isFeatureUnlocked(_ feature: String) -> Bool
    func getFeatureCost(_ feature: String) -> Int
    func unlockFeature(_ feature: String) async throws
    
    // UI integration
    func showFeaturePrompt(for feature: String)
    func showKeyPurchaseFlow()
}

App Configuration

struct VUAppFeatureConfig {
    let appId: String
    let features: [String: VUFeature]
    let freeFeatures: [String]
}

struct VUFeature {
    let id: String
    let name: String
    let description: String
    let cost: Int
    let category: String
}

Purchase Flow Architecture

Universal Key Pack Purchase

1. User initiates purchase in any app or web portal
2. Platform processes payment (Apple/Google/Stripe/PayPal/Steam)
3. Key server validates transaction and generates keys
4. Keys added to user's wallet with automatic sync
5. Community donations distributed automatically
6. Bonus keys added based on pack tier

App-Specific Feature Unlock

1. User taps locked feature in app
2. App checks wallet balance via VUKeyWallet
3. App shows cost and confirmation UI
4. User confirms spending X keys
5. Keys deducted from wallet with transaction record
6. Feature unlocks in app immediately
7. Transaction syncs across devices

Multi-Platform Sales Integration

Key Server Endpoints (Enhanced)

# Purchase (Universal)
POST /api/v1/keys/purchase/apple
POST /api/v1/keys/purchase/google  
POST /api/v1/keys/purchase/stripe
POST /api/v1/keys/purchase/paypal
POST /api/v1/keys/purchase/steam

# Wallet Management (Universal)
GET  /api/v1/wallet/:userId
POST /api/v1/wallet/spend
POST /api/v1/wallet/sync
GET  /api/v1/wallet/history

# App Integration (Per-App)
GET  /api/v1/apps/:appId/features
POST /api/v1/apps/:appId/unlock
GET  /api/v1/apps/:appId/unlocked/:userId

# Community (Universal)
POST /api/v1/community/donate
POST /api/v1/community/share
GET  /api/v1/community/pool

Database Schema

-- Universal wallet system
wallets (user_id, key_balance, created_at, updated_at)

-- Universal transaction log
key_transactions (
    id, user_id, type, amount, 
    app_id, feature_id, platform, 
    transaction_id, created_at
)

-- Per-app feature definitions
app_features (
    app_id, feature_id, name, 
    description, cost, category, active
)

-- Per-user unlocked features
user_features (
    user_id, app_id, feature_id, 
    unlocked_at, cost_paid
)

-- Universal community pool
community_donations (
    id, donor_id, amount, donated_at, 
    claimed_by, claimed_at
)

VoiceUwu Integration Example

Feature Configuration

// VoiceUwu app defines its features
let voiceUwuConfig = VUAppFeatureConfig(
    appId: "com.uwuapps.voiceuwu",
    features: [
        "advanced_monitors": VUFeature(
            id: "advanced_monitors",
            name: "Advanced Voice Monitors", 
            description: "Breathing, articulation, tone monitors",
            cost: 2,
            category: "analysis"
        ),
        "circle_trail": VUFeature(
            id: "circle_trail",
            name: "Circle Trail Visualization",
            description: "Visual pitch history with timing",
            cost: 3,
            category: "visualization"  
        )
        // ... more features
    ]
)

UI Integration

// In VoiceUwu app
@State private var showingKeyPurchase = false

Button("Advanced Monitors (2 keys)") {
    if featureGate.isFeatureUnlocked("advanced_monitors") {
        // Show feature
    } else if keyWallet.getKeyBalance() >= 2 {
        // Prompt to spend keys
        featureGate.unlockFeature("advanced_monitors")
    } else {
        // Show purchase flow
        showingKeyPurchase = true
    }
}
.sheet(isPresented: $showingKeyPurchase) {
    KeyPurchaseView(minKeys: 2)
}

Portable Benefits

For Developers

• Reusable infrastructure: Same purchase/wallet system across apps
• Flexible pricing: Each app sets its own feature costs
• Cross-app revenue: Users buy keys once, spend across multiple apps
• Community features: Built-in sharing and donation system

For Users

• Universal wallet: Keys work across all your apps
• Transparent pricing: Clear cost per feature
• Flexible spending: Buy only features you want
• Community participation: Help others through donations

For Ecosystem

• Cross-promotion: Apps can reference the key system
• Network effects: More apps = more value for key holders
• Sustainable model: $3/key maintains healthy margins
• Community growth: Shared community pool across apps

Implementation Strategy

1. Build portable core (key wallet, purchase system, community features)
2. Integrate VoiceUwu as first app with per-feature costs
3. Add other apps using same infrastructure but different feature definitions
4. Cross-promote through shared key economy
5. Scale community as more apps join the ecosystem

This creates a sustainable, scalable monetization platform that can support multiple apps while maintaining user choice and community engagement.