diff --git a/docs/dev/design/mc-base-currency-implementation.md b/docs/dev/design/mc-base-currency-implementation.md new file mode 100644 index 0000000..a49f81b --- /dev/null +++ b/docs/dev/design/mc-base-currency-implementation.md @@ -0,0 +1,110 @@ +# MC Base Currency Implementation Plan + +## Overview +Switch the Mycelium marketplace from USD to MC (Mycelium Credit) as the base currency while preserving identical UX for USD users through 1:1 exchange rate. + +## Critical Requirements +- **MC as Base**: All internal calculations use MC as reference currency +- **USD UX Preservation**: Users selecting USD get identical experience to current system +- **1:1 Exchange Rate**: 1 MC = 1 USD to maintain UX equivalence +- **Backward Compatibility**: No breaking changes for existing functionality + +## Implementation Phases + +### Phase 1: Core Currency Service Overhaul +- [ ] Update `CurrencyService::get_supported_currencies()` to make MC base currency +- [ ] Change MC `is_base_currency: true` and `exchange_rate_to_base: dec!(1.0)` +- [ ] Update USD `is_base_currency: false` and `exchange_rate_to_base: dec!(1.0)` +- [ ] Recalculate all other currency rates relative to MC (not USD) +- [ ] Update `CurrencyService::get_base_currency()` to return MC +- [ ] Update `convert_amount()` method to use MC as base reference +- [ ] Update `get_exchange_rate_to_base()` to use MC as base +- [ ] Update `get_all_exchange_rates()` to use MC as base +- [ ] Update `get_currency_stats()` base currency reporting + +### Phase 2: System-Wide Defaults Update +- [ ] Change `CurrencyService` default_display_currency from "USD" to "MC" +- [ ] Update user preference defaults in `UserPersistentData` from "USD" to "MC" +- [ ] Update model builders default currency from "USD" to "MC" +- [ ] Update controller response defaults from "USD" to "MC" +- [ ] Update template fallback values from "USD" to "MC" +- [ ] Update navbar service defaults from "USD" to "MC" + +### Phase 3: Service Layer Updates +- [ ] Update `UserPersistence` default display_currency from "USD" to "MC" +- [ ] Update `AutoTopUpService` USD references to use base currency +- [ ] Update `InstantPurchaseService` USD references to use base currency +- [ ] Update `OrderService` base currency references +- [ ] Update `ProductService` base currency handling +- [ ] Update `Wallet` service currency defaults +- [ ] Update `PoolService` token references from "USD" to base currency +- [ ] Update `ResourceProvider` base currency references + +### Phase 4: Controller Updates +- [ ] Update `CurrencyController` base currency responses +- [ ] Update `DashboardController` currency defaults and responses +- [ ] Update `WalletController` currency handling +- [ ] Update `OrderController` currency processing +- [ ] Update `MarketplaceController` currency defaults +- [ ] Update `PoolController` currency references +- [ ] Update all hardcoded "USD" strings in controller responses + +### Phase 5: Model Updates +- [ ] Update `MarketplaceCurrencyConfig` base_currency default +- [ ] Update `Product` model base_currency defaults +- [ ] Update `Order` model base currency references +- [ ] Update `Transaction` model currency defaults +- [ ] Update builder patterns to use MC as default +- [ ] Update all model default values from "USD" to "MC" + +### Phase 6: Template Updates +- [ ] Update hardcoded currency defaults in HTML templates +- [ ] Update JavaScript currency handling +- [ ] Update template variables and fallbacks +- [ ] Ensure dynamic currency selectors work with MC base + +### Phase 7: Testing & Validation +- [ ] Update unit tests to expect MC as base currency +- [ ] Update integration tests for currency conversions +- [ ] Test USD user experience preservation +- [ ] Validate all currency conversion accuracy +- [ ] Test edge cases and error handling +- [ ] Performance test currency operations + +### Phase 8: Documentation & Migration +- [ ] Update code comments referencing USD as base +- [ ] Update API documentation +- [ ] Create migration guide for existing data +- [ ] Update configuration examples +- [ ] Document exchange rate change process + +## UX Preservation Validation Checklist +- [ ] USD users see identical prices to current system +- [ ] Currency conversion works bidirectionally +- [ ] All formatting remains consistent +- [ ] User preferences persist correctly +- [ ] Wallet balances display correctly +- [ ] Transaction history shows correct values +- [ ] Checkout process works identically + +## Risk Mitigation +- **Data Migration**: Ensure existing user data migrates correctly +- **API Compatibility**: Maintain backward compatibility +- **Performance**: Monitor currency conversion performance +- **Error Handling**: Comprehensive error handling for edge cases +- **Rollback Plan**: Ability to rollback if issues arise + +## Success Criteria +- [ ] MC is the internal base currency for all calculations +- [ ] USD users experience no functional differences +- [ ] All currency conversions work accurately +- [ ] System performance remains acceptable +- [ ] All tests pass +- [ ] Documentation is updated +- [ ] No breaking changes for existing integrations + +## Future Considerations +- Exchange rate flexibility for future changes (1 MC = 10 USD, etc.) +- Additional currency support +- Multi-currency wallet support +- Advanced currency conversion features \ No newline at end of file