projectmycelium/docs/dev/design/archive/plan_refactor_phase_2.md

Enhanced Project Mycelium Refactor Plan - Phase 2

Overview

This document outlines the enhanced implementation plan for the Project Mycelium based on the successful progress from Phase 1 and incorporates OpenRouter-inspired UX improvements. The goal is to create an optimal user experience with streamlined credit management, auto top-up functionality, and improved Buy Now capabilities.

Current System Analysis

Existing Implementation Status

• Currency System: TFP-based with 1 TFP = 0.1 USD exchange rate
• Navbar: OpenRouter-style dropdown already implemented with wallet balance display
• Wallet Controller: Comprehensive implementation with instant purchase and quick top-up
• Buy Now Functionality: Partially implemented but currently non-functional
• Currency Preferences: Fully implemented with USD, EUR, CAD, TFP options
• Quick Top-up Amounts: Configurable user preferences already in place

Key Findings from Code Analysis

1. Strong Foundation: The existing architecture already supports most requested features
2. Naming Convention: Current system uses "Wallet" terminology throughout codebase
3. Buy Now Issue: Frontend buttons exist but lack proper event handlers
4. Auto Top-Up: Not yet implemented but infrastructure is ready
5. Pools Integration: Currently separate from main wallet flow

Enhanced Requirements Analysis

User Feedback Integration

Based on your requirements, here are the key changes needed:

1. Currency Rebranding

• Change: TFP → TFC (ThreeFold Credits)
• Exchange Rate: 10 TFC = 1 USD (instead of 1 TFP = 0.1 USD)
• Impact: Requires currency service updates and display formatting changes

2. Naming Convention Decision

Recommendation: Keep "Wallet" terminology

• Rationale: Changing to "Credits" would require extensive route and controller refactoring
• Alternative: Update UI labels while maintaining backend naming
• Benefit: Maintains existing functionality while improving UX

3. Auto Top-Up Implementation

• Feature: OpenRouter-style auto top-up with configurable thresholds
• Integration: Seamless with existing quick top-up infrastructure
• User Control: Toggle on/off with customizable amounts and triggers

4. Buy Now Functionality Fix

• Issue: Frontend buttons exist but lack proper JavaScript event handlers
• Solution: Implement missing event listeners and API integration
• Enhancement: Integrate with auto top-up for insufficient balance scenarios

Technical Implementation Plan

Phase 2A: Currency System Enhancement (Week 1)

2A.1 Currency Service Updates

// File: src/services/currency.rs
impl CurrencyService {
    pub fn get_tfc_exchange_rate() -> Decimal {
        dec!(0.1) // 10 TFC = 1 USD, so 1 TFC = 0.1 USD
    }
    
    pub fn convert_usd_to_tfc(usd_amount: Decimal) -> Decimal {
        usd_amount * dec!(10) // 1 USD = 10 TFC
    }
    
    pub fn convert_tfc_to_usd(tfc_amount: Decimal) -> Decimal {
        tfc_amount / dec!(10) // 10 TFC = 1 USD
    }
}

2A.2 Display Updates

• Update all "TFP" references to "TFC" in templates
• Modify currency formatting to show TFC amounts
• Update exchange rate calculations throughout the system

2A.3 Database Migration Strategy

• Backward Compatibility: Maintain existing TFP data structure
• Display Layer: Convert TFP to TFC for display (multiply by 10)
• New Transactions: Store in TFC format going forward

Phase 2B: Auto Top-Up Implementation (Week 2)

2B.1 Auto Top-Up Data Models

// File: src/models/user.rs
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct AutoTopUpSettings {
    pub enabled: bool,
    pub threshold_amount: Decimal, // In TFC
    pub topup_amount: Decimal,     // In TFC
    pub payment_method: String,
    pub currency: String,          // User's preferred currency for payment
    pub last_topup: Option<DateTime<Utc>>,
    pub daily_limit: Option<Decimal>,
    pub monthly_limit: Option<Decimal>,
}

2B.2 Auto Top-Up Service

// File: src/services/auto_topup.rs
pub struct AutoTopUpService {
    currency_service: CurrencyService,
    payment_service: PaymentService,
}

impl AutoTopUpService {
    pub async fn check_and_execute_topup(&self, user_email: &str) -> Result<Option<TopUpResult>, String> {
        // Check if auto top-up is enabled and threshold is met
        // Execute top-up if conditions are satisfied
        // Return result with transaction details
    }
    
    pub fn should_trigger_topup(&self, current_balance: Decimal, settings: &AutoTopUpSettings) -> bool {
        settings.enabled && current_balance < settings.threshold_amount
    }
}

2B.3 Integration Points

• Purchase Flow: Check auto top-up before insufficient balance errors
• Wallet Page: Auto top-up configuration UI
• Background Service: Periodic balance checks for active users

Phase 2C: Buy Now Functionality Fix (Week 2)

2C.1 Frontend JavaScript Enhancement

// File: src/views/base.html (enhanced buyNow function)
window.buyNow = async function(productId, productName, productCategory, quantity, unitPriceTfc, providerId, providerName, specifications = {}) {
    try {
        // Check if auto top-up is enabled and balance is sufficient
        const affordabilityCheck = await fetch(`/api/wallet/check-affordability?amount=${unitPriceTfc * quantity}`);
        const affordabilityResult = await affordabilityCheck.json();
        
        if (!affordabilityResult.can_afford && affordabilityResult.shortfall_info) {
            // Trigger auto top-up if enabled, otherwise prompt user
            const autoTopUpResult = await handleInsufficientBalance(affordabilityResult.shortfall_info);
            if (!autoTopUpResult.success) {
                return; // User cancelled or auto top-up failed
            }
        }
        
        // Proceed with purchase
        const response = await fetch('/api/wallet/instant-purchase', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                product_id: productId,
                product_name: productName,
                product_category: productCategory,
                quantity: quantity,
                unit_price_tfc: unitPriceTfc,
                provider_id: providerId,
                provider_name: providerName,
                specifications: specifications
            })
        });
        
        const result = await response.json();
        handlePurchaseResult(result);
        
    } catch (error) {
        console.error('Buy now error:', error);
        showErrorMessage('Failed to process purchase. Please try again.');
    }
};

2C.2 Event Handler Registration

// File: marketplace templates
document.addEventListener('DOMContentLoaded', function() {
    // Register Buy Now button event handlers
    document.querySelectorAll('.buy-now-btn').forEach(button => {
        button.addEventListener('click', function() {
            const productId = this.dataset.productId;
            const productName = this.dataset.productName;
            const unitPrice = parseFloat(this.dataset.unitPrice);
            const currency = this.dataset.currency;
            
            // Convert to TFC if needed
            const unitPriceTfc = currency === 'TFC' ? unitPrice : convertToTfc(unitPrice, currency);
            
            buyNow(productId, productName, 'compute', 1, unitPriceTfc, 'provider', 'Provider Name');
        });
    });
});

Phase 2D: UI/UX Enhancements (Week 3)

2D.1 Wallet Page Enhancements

• Auto Top-Up Section: Configuration panel with toggle and settings
• Credit Display: Prominent TFC balance with USD equivalent
• Quick Actions: Streamlined top-up with preset amounts
• Transaction History: Enhanced with auto top-up transaction types

2D.2 Navbar Improvements

• Balance Display: Show TFC with currency indicator
• Quick Top-Up: Direct access from dropdown
• Auto Top-Up Status: Visual indicator when enabled

2D.3 Marketplace Integration

• Buy Now Buttons: Functional across all product categories
• Balance Warnings: Proactive notifications for low balances
• Auto Top-Up Prompts: Seamless integration with purchase flow

Phase 2E: Pools Page Analysis and Recommendation

Current Pools Functionality

• TFP Trading: Exchange TFP for fiat currencies (USD, EUR, CAD)
• Crypto Trading: TFP/TFT and TFP/PEAQ exchanges
• Staking: TFP staking with marketplace benefits

Recommendation: Keep Pools Page

Rationale:

1. Advanced Features: Pools provide sophisticated trading and staking capabilities
2. Power Users: Advanced users benefit from direct trading controls
3. Staking Benefits: Marketplace discounts and reputation boosts
4. Complementary: Works alongside simplified wallet top-up for different user needs

Enhancement Strategy:

• Simplified Access: Add "Advanced Trading" link from wallet page
• User Guidance: Clear distinction between simple top-up and advanced trading
• Integration: Auto top-up can use pool liquidity for better rates

API Enhancements

New Endpoints

// Auto Top-Up Management
POST /api/wallet/auto-topup/configure  // Configure auto top-up settings
GET  /api/wallet/auto-topup/status     // Get current auto top-up status
POST /api/wallet/auto-topup/trigger    // Manually trigger auto top-up

// Enhanced Purchase Flow
POST /api/wallet/purchase-with-topup   // Purchase with automatic top-up
GET  /api/wallet/purchase-preview      // Preview purchase with balance check

// Currency Conversion
GET  /api/currency/tfc-rates           // Get TFC exchange rates
POST /api/currency/convert-to-tfc      // Convert amount to TFC

Enhanced Existing Endpoints

// Enhanced navbar data with auto top-up status
GET /api/navbar/dropdown-data
// Response includes:
{
    "wallet_balance_formatted": "150.0 TFC",
    "wallet_balance_usd": "$15.00",
    "display_currency": "TFC",
    "auto_topup_enabled": true,
    "auto_topup_threshold": "20.0 TFC"
}

Database Schema Updates

UserPersistentData Extensions

pub struct UserPersistentData {
    // ... existing fields ...
    pub auto_topup_settings: Option<AutoTopUpSettings>,
    pub display_currency: Option<String>, // "TFC", "USD", "EUR", "CAD"
    pub quick_topup_amounts_tfc: Option<Vec<Decimal>>, // Amounts in TFC
    pub tfc_migration_completed: Option<bool>, // Track TFP->TFC migration
}

Transaction Model Updates

pub enum TransactionType {
    // ... existing variants ...
    AutoTopUp {
        trigger_amount: Decimal,
        payment_method: String,
        currency_used: String,
    },
    InstantPurchase {
        product_id: String,
        auto_topup_triggered: bool,
    },
}

Migration Strategy

Phase 1: Backward Compatible Changes

1. Display Layer: Convert existing TFP to TFC for display (multiply by 10)
2. New Features: Implement auto top-up with TFC amounts
3. API Compatibility: Support both TFP and TFC in API responses

Phase 2: Data Migration

1. User Preference: Allow users to opt into TFC display
2. Gradual Migration: Convert user data on first login after update
3. Fallback Support: Maintain TFP compatibility for legacy integrations

Phase 3: Full TFC Adoption

1. Default to TFC: New users start with TFC
2. Legacy Support: Maintain TFP conversion for existing data
3. Documentation: Update all references to use TFC terminology

User Experience Flow

Enhanced Purchase Flow

1. Product Discovery: User browses marketplace with TFC pricing
2. Buy Now Click: Instant purchase attempt
3. Balance Check: Automatic balance verification
4. Auto Top-Up: If enabled and needed, automatic top-up triggers
5. Purchase Completion: Seamless transaction with updated balance
6. Confirmation: Clear success message with transaction details

Auto Top-Up Configuration Flow

1. Wallet Access: User navigates to wallet page
2. Auto Top-Up Section: Prominent configuration panel
3. Enable Toggle: Simple on/off switch
4. Threshold Setting: "When credits are below: [amount] TFC"
5. Top-Up Amount: "Purchase this amount: [amount] in [currency]"
6. Payment Method: Select from saved payment methods
7. Save Settings: Immediate activation with confirmation

Low Balance Handling

1. Proactive Notification: Warning when approaching threshold
2. Auto Top-Up Trigger: Automatic execution when threshold reached
3. Manual Override: Option to manually top-up anytime
4. Failure Handling: Graceful degradation if auto top-up fails

Testing Strategy

Integration Tests

• Auto Top-Up Flow: End-to-end testing of threshold detection and execution
• Buy Now Functionality: Complete purchase flow with balance checks
• Currency Conversion: TFP to TFC conversion accuracy
• Cross-Browser: Ensure JavaScript functionality across browsers

User Experience Tests

• Mobile Responsiveness: Auto top-up configuration on mobile devices
• Performance: Fast balance checks and purchase processing
• Error Handling: Clear error messages and recovery options
• Accessibility: Screen reader compatibility for all new features

Load Testing

• Concurrent Purchases: Multiple users buying simultaneously
• Auto Top-Up Scaling: High-volume automatic top-up processing
• Database Performance: Efficient balance checks and updates

Security Considerations

Auto Top-Up Security

• Rate Limiting: Prevent excessive auto top-up attempts
• Daily/Monthly Limits: User-configurable spending limits
• Payment Method Validation: Secure payment processing
• Audit Trail: Complete logging of all auto top-up activities

Purchase Security

• Double-Spend Prevention: Atomic balance checks and deductions
• Session Validation: Secure user authentication for purchases
• Input Validation: Sanitize all purchase parameters
• Fraud Detection: Monitor for unusual purchase patterns

Performance Optimizations

Balance Checking

• Caching Strategy: Cache user balances with appropriate TTL
• Batch Processing: Group balance checks for efficiency
• Database Indexing: Optimize queries for user balance retrieval

Auto Top-Up Processing

• Asynchronous Processing: Non-blocking auto top-up execution
• Queue Management: Handle high-volume top-up requests
• Retry Logic: Robust handling of payment failures

Monitoring and Analytics

Key Metrics

• Auto Top-Up Adoption: Percentage of users enabling auto top-up
• Purchase Success Rate: Buy Now vs Add to Cart conversion
• Balance Utilization: Average user balance and top-up frequency
• Payment Method Preferences: Most popular top-up methods

Alerting

• Failed Auto Top-Ups: Monitor and alert on payment failures
• High Error Rates: Track purchase and top-up error rates
• Performance Degradation: Monitor response times for critical flows

Implementation Timeline

Week 1: Foundation

• Currency service updates for TFC
• Database schema extensions
• Basic auto top-up data models

Week 2: Core Features

• Auto top-up service implementation
• Buy Now functionality fixes
• Frontend JavaScript enhancements

Week 3: UI/UX Polish

• Wallet page auto top-up configuration
• Navbar enhancements
• Marketplace integration improvements

Week 4: Testing and Deployment

• Comprehensive testing
• Performance optimization
• Production deployment with monitoring

Success Metrics

User Experience

• Reduced Purchase Friction: Faster time from product discovery to purchase
• Increased Auto Top-Up Adoption: Target 30% of active users
• Higher Buy Now Usage: Increase instant purchases vs cart usage

Technical

• Improved Purchase Success Rate: Target 99%+ success rate
• Fast Response Times: <500ms for balance checks and purchases
• Zero Data Loss: Maintain transaction integrity throughout

Business

• Increased Transaction Volume: More frequent, smaller purchases
• Improved User Retention: Better UX leading to higher engagement
• Reduced Support Tickets: Fewer balance-related user issues

Risk Mitigation

Technical Risks

• Currency Conversion Errors: Extensive testing of TFP to TFC conversion
• Auto Top-Up Failures: Robust error handling and user notification
• Performance Impact: Load testing and optimization before deployment

User Experience Risks

• Confusion with New Currency: Clear communication and gradual migration
• Auto Top-Up Concerns: Transparent controls and spending limits
• Purchase Flow Disruption: Maintain existing cart functionality alongside Buy Now

Business Risks

• Payment Processing Issues: Multiple payment method support and fallbacks
• Regulatory Compliance: Ensure auto top-up meets financial regulations
• User Trust: Transparent pricing and clear terms for auto top-up

Conclusion

This enhanced plan builds upon the strong foundation already established in the Project Mycelium. The key improvements focus on:

1. Optimal UX: OpenRouter-inspired auto top-up with seamless purchase flow
2. Currency Evolution: Smooth transition from TFP to TFC with better user understanding
3. Functional Buy Now: Fix existing issues and integrate with auto top-up
4. Strategic Pools Retention: Keep advanced features while simplifying common workflows

The implementation prioritizes user experience while maintaining the robust architecture and ensuring backward compatibility. The phased approach allows for careful testing and gradual rollout of new features.

By keeping the "Wallet" terminology in the backend while enhancing the user-facing experience, we achieve the best of both worlds: minimal technical disruption with maximum UX improvement.