keys-for-all/docs/VOICEUWU_KEY_SYSTEM.md

VoiceUwu Key System: Per-Feature Marketplace

Overview

Simple key-based monetization for VoiceUwu where users buy key packs and spend individual keys to unlock specific features. Based on the $3/key model from KEY_PACK_PRICING.md.

Core Concept

Keys as Currency: Users buy key packs, then spend keys on individual VoiceUwu features

• 1 Key = $3.00
• All features cost 1 key ($3 each)
• Buy only what you need - no forced tiers

VoiceUwu Feature Pricing

All features cost 1 key ($3) each

Available Features

• Advanced Breathing Monitor: 1 key ($3)
• Circle Trail Visualization: 1 key ($3)
• Dark Mode: 1 key ($3)
• Enhanced Haptic Feedback: 1 key ($3)
• Hide Monetization UI: 1 key ($3)
• CSV Data Export: 1 key ($3)
• Multi-Monitor Dashboard: 1 key ($3)

Preorder Features (Vote with Keys)

• Multi-Dimensional Voice Interface: 1 key preorder
• Interactive Coaching System: 1 key preorder
• Rhythm Monitor: 1 key preorder
• Session Recording & Replay: 1 key preorder

See VOICEUWU_FEATURE_LIST.md for complete feature catalog

Key Pack Purchasing

Available Across 5 Platforms

• Apple App Store (iOS/macOS) - In-app purchase
• Google Play Store (Android) - In-app purchase
• Web Portal - Stripe checkout
• Web Portal - PayPal checkout
• Steam Store - Steam purchase

Key Pack Options (from KEY_PACK_PRICING.md)

Keys	Price	Bonus Keys	Community Donated	You Get
1	$3	0	0	1
5	$15	1	1	6
10	$30	1	3	11
20	$60	2	3	22
50	$150	5	10	55

System Architecture

Core Components

VoiceUwu App
├── VUKeyWallet              # Stores user's key balance
├── VUFeaturePurchase        # Handle spending keys on features
├── VUFeatureGate           # Lock/unlock features based on purchases
└── VUKeyPurchaseManager    # Handle key pack purchases

Key Server
├── Key pack sales          # Process purchases from 5 platforms
├── Wallet management       # Track user key balances
├── Feature unlocking       # Record feature purchases
└── Community pool          # Handle donated keys

Key Wallet

protocol VUKeyWalletProtocol {
    func getBalance() -> Int
    func spendKeys(_ amount: Int, for feature: String) async throws
    func addKeys(_ amount: Int, from purchase: Purchase) async throws
    func syncBalance() async throws
}

Feature Purchasing

protocol VUFeaturePurchaseProtocol {
    func purchaseFeature(_ feature: VUFeature) async throws
    func isFeatureUnlocked(_ feature: String) -> Bool
    func getFeatureCost(_ feature: String) -> Int
}

struct VUFeature {
    let id: String
    let name: String
    let cost: Int           // Number of keys required
    let description: String
}

Purchase Flow

Buying Key Packs

1. User taps "Buy Keys" in VoiceUwu
2. Selects key pack (1, 5, 10, 20, 50 keys)
3. Platform processes payment (Apple/Google/Stripe/PayPal/Steam)
4. Key server validates purchase and adds keys to wallet
5. Bonus keys and community donations distributed automatically
6. User's key balance updates in app

Unlocking Features

1. User taps locked feature in VoiceUwu
2. App shows cost: "Advanced Monitors - 2 keys"
3. User confirms spending keys
4. Keys deducted from wallet
5. Feature unlocks immediately
6. Purchase syncs across devices

User Interface

Key Balance Display

🗝️ 15 keys    [Buy More]

Feature Lock UI

🔒 Advanced Monitors
   Unlock for 2 keys
   [Try Demo] [Unlock]

Purchase Confirmation

Unlock Advanced Monitors?
Cost: 2 keys ($6 value)
Your balance: 15 keys → 13 keys
[Cancel] [Unlock Feature]

Community Features

Auto-Donation (from KEY_PACK_PRICING.md)

• Larger key packs automatically donate keys to community pool
• 10-pack donates 3 keys, 20-pack donates 3 keys, etc.
• Users can see impact: "Your purchases helped 12 users this month"

Manual Sharing

• Share individual keys with friends
• Generate gift codes
• Email integration

Technical Implementation

Server Endpoints

POST /purchase/keys/apple     # Apple in-app purchase
POST /purchase/keys/google    # Google Play purchase
POST /purchase/keys/stripe    # Stripe web purchase
POST /purchase/keys/paypal    # PayPal web purchase
POST /purchase/keys/steam     # Steam purchase

GET  /wallet/:userId          # Get key balance
POST /wallet/spend            # Spend keys on feature
POST /features/unlock         # Unlock specific feature
GET  /features/unlocked/:userId  # Get unlocked features

Local Storage

• Key balance cached locally
• Unlocked features stored securely
• Sync on app launch and purchase
• Offline feature access once unlocked

Revenue Model

Simple & Transparent:

• Clear $3/key pricing
• Pay only for features you want
• Bulk discounts encourage larger purchases
• Community aspect drives engagement

Example User Journey:

1. User downloads VoiceUwu (free basic features)
2. Wants advanced monitors → sees "2 keys required"
3. Buys 5-key pack for $15 (gets 6 keys total)
4. Unlocks advanced monitors (2 keys)
5. Has 4 keys left for other features
6. Community gets 1 donated key automatically

This keeps it focused on VoiceUwu while supporting the per-feature marketplace model from KEY_PACK_PRICING.md.