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

OpenRouter-Inspired Marketplace Enhancement Plan

Overview

This document outlines the implementation plan for enhancing the Project Mycelium with OpenRouter-inspired payment features while maintaining all existing functionality. The goal is to add streamlined "buy now" capabilities and improved wallet management alongside the current cart-based shopping experience.

Current System Analysis

Architecture Patterns

• Builder Pattern: Services use ServiceName::builder().build() pattern
• Service Layer: Clean separation with dedicated services (CurrencyService, WalletController, etc.)
• Controller Pattern: RESTful endpoints with JSON responses
• Template Engine: Tera templating with context-based rendering
• Session Management: Actix-web sessions for user state
• Persistence: UserPersistence service for data management

Current Currency System

• Base Currency: TFP (ThreeFold Points)
• Exchange Rate: 1 TFP = 0.1 USD (configurable)
• Display Options: Currently supports multiple currencies (USD, EUR, TFT, PEAQ)
• User Preferences: Currency preferences stored per user

Current Purchase Flow

1. Browse marketplace → Add to cart → Checkout → Purchase
2. TFP purchase via wallet page or TFP pools
3. TFP pools support trading: TFP/Fiat, TFP/TFT, TFP/PEAQ

Enhancement Goals

1. Currency Display Improvements

• Default Currency: Set USD as default display currency for new users
• TFP Display Option: Add TFP as a display currency choice alongside fiat currencies
• User Choice: Users can choose any supported currency (TFP, USD, CAD, EUR, etc.) for price display
• Internal Processing: All transactions remain TFP-based internally

2. OpenRouter-Style Navbar

Replace simple "Hello, USERNAME" with dropdown menu containing:

• User name/email
• Current wallet balance in user's preferred display currency
• "Top Up Wallet" / "Buy Credits" quick action
• Settings link
• Logout option

3. Enhanced Wallet Top-Up

• Direct Currency Input: "Add $20" converts to TFP automatically
• Quick Amount Buttons: Preset amounts ($10, $20, $50, $100)
• Real-time Conversion: Show TFP equivalent during input
• Streamlined Flow: Fewer steps from intent to completion

4. Buy Now Functionality

• Instant Purchase: "Buy Now" buttons alongside "Add to Cart"
• Direct Deduction: Skip cart, deduct TFP immediately
• Balance Check: Automatic fallback to top-up if insufficient funds
• Immediate Deployment: For applicable services/products

Technical Implementation Plan

Phase 1: Currency Service Enhancement

1.1 Extend CurrencyService

// File: src/services/currency.rs
impl CurrencyService {
    pub fn builder() -> CurrencyServiceBuilder {
        CurrencyServiceBuilder::new()
            .with_default_display_currency("USD")
            .with_tfp_display_option(true)
    }
}

1.2 Update Currency Models

// File: src/models/currency.rs
// Add TFP as display currency option
// Ensure USD is default for new users
// Maintain configurable TFP exchange rate

1.3 Currency Preference Storage

// File: src/services/user_persistence.rs
// Extend UserPersistentData to include display_currency preference
// Default to "USD" for new users
// Support "TFP", "USD", "CAD", "EUR", etc.

Phase 2: Navbar Enhancement

2.1 Create NavbarService

// File: src/services/navbar.rs
pub struct NavbarService;

impl NavbarService {
    pub fn builder() -> NavbarServiceBuilder {
        NavbarServiceBuilder::new()
    }
    
    pub fn get_user_dropdown_data(&self, session: &Session) -> NavbarDropdownData {
        // Get user info, wallet balance in preferred currency, etc.
    }
}

2.2 Update Base Template

<!-- File: src/views/base.html -->
<!-- Replace simple greeting with dropdown menu -->
<!-- Include wallet balance, top-up button, settings link -->

Phase 3: Instant Purchase System

3.1 Create InstantPurchaseService

// File: src/services/instant_purchase.rs
pub struct InstantPurchaseService;

impl InstantPurchaseService {
    pub fn builder() -> InstantPurchaseServiceBuilder {
        InstantPurchaseServiceBuilder::new()
    }
    
    pub async fn execute_instant_purchase(&self, request: InstantPurchaseRequest) -> InstantPurchaseResult {
        // Check TFP balance
        // Deduct amount
        // Create transaction
        // Trigger deployment/fulfillment
    }
}

3.2 Extend WalletController

// File: src/controllers/wallet.rs
impl WalletController {
    pub async fn instant_purchase(
        request: web::Json<InstantPurchaseRequest>,
        session: Session,
    ) -> Result<impl Responder> {
        // Handle buy-now requests
    }
    
    pub async fn quick_topup(
        request: web::Json<QuickTopupRequest>,
        session: Session,
    ) -> Result<impl Responder> {
        // Handle streamlined top-up
    }
}

3.3 Update Marketplace Templates

<!-- Add buy-now buttons to all product listings -->
<!-- Maintain existing add-to-cart functionality -->
<!-- Include balance check and top-up prompts -->

Phase 4: Enhanced Wallet Interface

4.1 Wallet Page Improvements

<!-- File: src/views/wallet/index.html -->
<!-- Prominent display of balance in user's preferred currency -->
<!-- Quick top-up with currency input -->
<!-- Preset amount buttons -->
<!-- Real-time conversion display -->

4.2 Currency Settings

<!-- File: src/views/dashboard/settings.html -->
<!-- Add currency preference selection -->
<!-- Include TFP and all supported fiat currencies -->
<!-- Real-time preview of balance in selected currency -->

API Endpoints

New Endpoints

• POST /api/wallet/instant-purchase - Execute buy-now purchase
• POST /api/wallet/quick-topup - Streamlined wallet top-up
• PUT /api/currency/set-display - Update user's display currency preference
• GET /api/navbar/dropdown-data - Get navbar dropdown information

Enhanced Endpoints

• GET /api/wallet/info - Include balance in user's preferred display currency
• GET /api/currency/user-preference - Return current display currency setting

Database Schema Changes

UserPersistentData Extensions

pub struct UserPersistentData {
    // ... existing fields ...
    pub display_currency: Option<String>, // "USD", "TFP", "CAD", etc.
    pub quick_topup_amounts: Option<Vec<Decimal>>, // Customizable preset amounts
}

Transaction Model Extensions

pub struct Transaction {
    // ... existing fields ...
    pub purchase_type: PurchaseType, // Cart, Instant, TopUp
    pub display_currency_used: Option<String>,
    pub display_amount: Option<Decimal>,
}

pub enum PurchaseType {
    CartPurchase,
    InstantPurchase,
    WalletTopUp,
    PoolExchange,
}

User Experience Flow

Buy Now Flow

1. User browses marketplace in their preferred display currency
2. Clicks "Buy Now" on a product
3. System checks TFP balance
4. If sufficient: Immediate purchase and deployment
5. If insufficient: Prompt for top-up with exact amount needed
6. Top-up in user's preferred currency, convert to TFP
7. Complete purchase automatically

Top-Up Flow

1. User clicks "Top Up" in navbar dropdown or wallet page
2. Enter amount in preferred currency (e.g., "$20")
3. System shows TFP conversion (e.g., "= 200 TFP")
4. Select payment method
5. Process payment and add TFP to wallet
6. Update balance display across all interfaces

Backward Compatibility

Preserved Functionality

• Cart System: Remains fully functional
• TFP Pools: All existing pool trading continues to work
• Existing APIs: No breaking changes to current endpoints
• User Data: Existing users retain all data and preferences
• Payment Methods: All current payment options remain available

Migration Strategy

• New users default to USD display currency
• Existing users keep current preferences
• TFP display option added to all currency selectors
• Gradual rollout of buy-now buttons alongside existing cart buttons

Testing Strategy

Integration Tests

• Cart and buy-now flows work together
• Currency conversion accuracy
• Session management with new features
• Backward compatibility with existing data

User Experience Tests

• Navbar dropdown functionality
• Wallet top-up flow
• Buy-now purchase flow
• Currency preference changes

Performance Tests

• Real-time currency conversion
• Balance checks for instant purchases
• Template rendering with new data

Implementation Timeline

Phase 1: Foundation (Week 1)

• Currency service enhancements
• TFP display option
• USD default for new users

Phase 2: UI/UX (Week 2)

• Navbar dropdown implementation
• Wallet page improvements
• Settings page currency selection

Phase 3: Buy Now (Week 3)

• Instant purchase service
• Buy-now buttons in marketplace
• Balance check and top-up integration

Phase 4: Polish & Testing (Week 4)

• Integration testing
• UI/UX refinements
• Performance optimization
• Documentation updates

Success Metrics

User Experience

• Reduced time from product discovery to purchase
• Increased wallet top-up frequency
• Higher conversion rates on marketplace items

Technical

• No regression in existing cart functionality
• Successful currency conversion accuracy
• Stable session management with new features

Business

• Maintained compatibility with TFP pools
• Seamless integration with existing payment systems
• Clear audit trail for all transaction types

Risk Mitigation

Technical Risks

• Currency Conversion Errors: Extensive testing of conversion logic
• Session Management: Careful handling of user state across new features
• Performance Impact: Optimize database queries for balance checks

User Experience Risks

• Confusion Between Flows: Clear UI distinction between cart and buy-now
• Currency Display Issues: Thorough testing of all currency combinations
• Balance Synchronization: Ensure real-time balance updates across interfaces

Business Risks

• Backward Compatibility: Comprehensive testing with existing user data
• TFP Pool Integration: Ensure no conflicts with existing pool functionality
• Payment Processing: Maintain all existing payment method support

Conclusion

This enhancement plan adds OpenRouter-inspired streamlined purchasing while preserving the robust existing marketplace functionality. The modular approach ensures clean integration with the current architecture and provides a foundation for future enhancements.

The key innovation is offering users choice: they can continue using the familiar cart-based shopping experience or opt for the new instant purchase flow, all while viewing prices in their preferred currency (including TFP itself).