crowd-funder-for-time-pwa/doc/migration-roadmap-next-steps.md

Migration Roadmap: Next Steps

Overview

This document outlines the immediate next steps for completing the TimeSafari database migration from Dexie to SQLite, based on the current status and progress documented across the codebase.

Current Status Summary

✅ Completed Achievements

1. Circular Dependencies Resolved - No active circular dependencies blocking development
2. PlatformServiceMixin Implemented - Core functionality with caching and utilities
3. Migration Tools Ready - Data comparison and transfer utilities functional
4. Core Data Migrated - Settings, accounts, and ActiveDid migration completed
5. Documentation Updated - All docs reflect current PlatformServiceMixin approach

🔄 Current Phase: Phase 2 - Active Migration

• DatabaseUtil Migration: 52 files still importing databaseUtil
• Contact Migration: Framework ready, implementation in progress
• File-by-File Migration: Ready to begin systematic migration

Immediate Next Steps (This Week)

🔴 Priority 1: Complete PlatformServiceMixin Independence

Step 1.1: Remove memoryLogs Dependency

// Current: PlatformServiceMixin imports from databaseUtil
import { memoryLogs } from "@/db/databaseUtil";

// Solution: Create self-contained implementation
const memoryLogs: string[] = [];

Files to modify:

• src/utils/PlatformServiceMixin.ts - Remove import, add self-contained implementation

Estimated time: 30 minutes

Step 1.2: Add Missing Utility Methods

Add these methods to PlatformServiceMixin:

• $parseJson() - Self-contained JSON parsing
• $generateInsertStatement() - SQL generation
• $generateUpdateStatement() - SQL generation
• $logConsoleAndDb() - Enhanced logging

Estimated time: 2 hours

🟡 Priority 2: Start File-by-File Migration

Step 2.1: Migrate Critical Files First

Based on the migration plan, start with these high-priority files:

1. src/App.vue - Main application (highest impact)
2. src/views/AccountViewView.vue - Core account management
3. src/views/ContactsView.vue - Core contact management
4. src/libs/util.ts - Utility functions used by many components
5. src/services/deepLinks.ts - Service layer

Migration pattern for each file:

// 1. Remove databaseUtil import
// Remove: import * as databaseUtil from "../db/databaseUtil";

// 2. Add PlatformServiceMixin
// Add: mixins: [PlatformServiceMixin],

// 3. Replace function calls
// Replace: databaseUtil.retrieveSettingsForActiveAccount()
// With: this.$settings()

// Replace: databaseUtil.logConsoleAndDb(message, isError)
// With: this.$logAndConsole(message, isError)

// Replace: databaseUtil.parseJsonField(value, defaultValue)
// With: this.$parseJson(value, defaultValue)

Estimated time: 1-2 hours per file (5 files = 5-10 hours)

Medium-Term Goals (Next 2 Weeks)

🟡 Priority 3: Systematic File Migration

Step 3.1: Migrate High-Usage Components (15 files)

Target components with databaseUtil imports:

• PhotoDialog.vue
• FeedFilters.vue
• UserNameDialog.vue
• ImageMethodDialog.vue
• OfferDialog.vue
• OnboardingDialog.vue
• PushNotificationPermission.vue
• GiftedPrompts.vue
• GiftedDialog.vue
• And 6 more...

Estimated time: 15-30 hours

Step 3.2: Migrate High-Usage Views (20 files)

Target views with databaseUtil imports:

• IdentitySwitcherView.vue
• ContactEditView.vue
• ContactGiftingView.vue
• ImportAccountView.vue
• OnboardMeetingMembersView.vue
• RecentOffersToUserProjectsView.vue
• ClaimCertificateView.vue
• NewActivityView.vue
• HelpView.vue
• NewEditProjectView.vue
• And 10+ more...

Estimated time: 20-40 hours

Step 3.3: Migrate Remaining Files (27 files)

Complete migration of all remaining files with databaseUtil imports.

Estimated time: 27-54 hours

🟢 Priority 4: Contact Migration Completion

Step 4.1: Complete Contact Migration Framework

• Implement contact import/export functionality
• Add contact validation and error handling
• Test contact migration with real data

Estimated time: 4-8 hours

Step 4.2: User Testing and Validation

• Test migration with various data scenarios
• Validate data integrity after migration
• Performance testing with large datasets

Estimated time: 8-16 hours

Long-Term Goals (Next Month)

🔵 Priority 5: Cleanup and Optimization

Step 5.1: Remove Unused databaseUtil Functions

After all files are migrated:

• Remove unused functions from databaseUtil.ts
• Update TypeScript interfaces
• Clean up legacy code

Estimated time: 4-8 hours

Step 5.2: Performance Optimization

• Optimize PlatformServiceMixin caching
• Add performance monitoring
• Implement database query optimization

Estimated time: 8-16 hours

Step 5.3: Legacy Dexie Removal

• Remove Dexie dependencies
• Clean up migration tools
• Update build configurations

Estimated time: 4-8 hours

Migration Commands and Tools

Automated Migration Script

Create a script to help with bulk migrations:

#!/bin/bash
# migrate-file.sh - Automated file migration helper

FILE=$1
if [ -z "$FILE" ]; then
    echo "Usage: ./migrate-file.sh <filename>"
    exit 1
fi

echo "Migrating $FILE..."

# 1. Backup original file
cp "$FILE" "$FILE.backup"

# 2. Remove databaseUtil imports
sed -i '/import.*databaseUtil/d' "$FILE"

# 3. Add PlatformServiceMixin import
sed -i '1i import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";' "$FILE"

# 4. Add mixin to component
sed -i '/mixins:/a \  PlatformServiceMixin,' "$FILE"

echo "Migration completed for $FILE"
echo "Please review and test the changes"

Migration Testing Commands

# Test individual file migration
npm run test -- --grep "ComponentName"

# Test database operations
npm run test:database

# Test migration tools
npm run test:migration

# Lint check
npm run lint

# TypeScript check
npx tsc --noEmit

Risk Mitigation

Incremental Migration Strategy

1. One file at a time - Minimize risk of breaking changes
2. Comprehensive testing - Test each migration thoroughly
3. Rollback capability - Keep databaseUtil.ts until migration complete
4. Documentation updates - Update docs as methods are migrated

Testing Strategy

1. Unit tests - Test individual component functionality
2. Integration tests - Test database operations
3. End-to-end tests - Test complete user workflows
4. Performance tests - Ensure no performance regression

Rollback Plan

1. Git branches - Each migration in separate branch
2. Backup files - Keep original files until migration verified
3. Feature flags - Ability to switch back to databaseUtil if needed
4. Monitoring - Watch for errors and performance issues

Success Metrics

Short-Term (This Week)

• PlatformServiceMixin completely independent
• 5 critical files migrated
• No new circular dependencies
• All tests passing

Medium-Term (Next 2 Weeks)

• 35+ files migrated (70% completion)
• Contact migration framework complete
• Performance maintained or improved
• User testing completed

Long-Term (Next Month)

• All 52 files migrated (100% completion)
• databaseUtil.ts removed or minimal
• Legacy Dexie code removed
• Migration tools cleaned up

Resource Requirements

Development Time

• Immediate (This Week): 8-12 hours
• Medium-Term (Next 2 Weeks): 35-70 hours
• Long-Term (Next Month): 16-32 hours
• Total Estimated: 59-114 hours

Testing Time

• Unit Testing: 20-30 hours
• Integration Testing: 10-15 hours
• User Testing: 8-12 hours
• Performance Testing: 5-8 hours
• Total Testing: 43-65 hours

Total Project Time

• Development: 59-114 hours
• Testing: 43-65 hours
• Documentation: 5-10 hours
• Total: 107-189 hours (2-4 weeks full-time)

Conclusion

The migration is well-positioned for completion with:

• ✅ No blocking circular dependencies
• ✅ PlatformServiceMixin mostly complete
• ✅ Clear migration path defined
• ✅ Comprehensive documentation available

The next steps focus on systematic file-by-file migration with proper testing and validation at each stage. The estimated timeline is 2-4 weeks for complete migration with thorough testing.

---

Author: Matthew Raymer Created: 2025-07-05 Status: Active Planning Last Updated: 2025-07-05 Note: This roadmap is based on current codebase analysis and documented progress