init projectmycelium

2025-09-01 21:37:01 -04:00
commit b41efb0e99
319 changed files with 128160 additions and 0 deletions
--- a/docs/dev/design/archive/plan_refactor_phase_2.md
+++ b/docs/dev/design/archive/plan_refactor_phase_2.md
@@ -0,0 +1,457 @@
+# 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
+```rust
+// 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
+```rust
+// 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
+```rust
+// 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
+```javascript
+// 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
+```javascript
+// 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
+```rust
+// 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
+```rust
+// 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
+```rust
+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
+```rust
+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.