crowd-funder-for-time-pwa/doc/migration-progress-tracker.md

Migration Progress Tracker: PlatformServiceMixin & 52-File Migration

Per-File Migration Workflow (MANDATORY)

For each file migrated:

1. First, migrate to PlatformServiceMixin (replace all databaseUtil usage, etc.).
2. Immediately after, standardize notify helper usage (property + created() pattern) and fix any related linter/type errors.

This two-step process is to be followed for every file, not as a global sweep at the end.

Anyone picking up this migration should follow this workflow for consistency and completeness.

---

Overview

This document tracks the progress of the 2-day sprint to complete PlatformServiceMixin implementation and migrate all 52 files from databaseUtil imports to PlatformServiceMixin usage.

Last Updated: $(date) Current Phase: Day 1 - PlatformServiceMixin Completion Overall Progress: 0% (0/52 files migrated)

---

🎯 DAY 1: PlatformServiceMixin Completion (4-6 hours)

Phase 1: Remove Circular Dependency (30 minutes)

Status: ⏳ PENDING Issue: PlatformServiceMixin imports memoryLogs from databaseUtil Solution: Create self-contained memoryLogs implementation

Tasks:

• Step 1.1: Remove memoryLogs import from PlatformServiceMixin.ts
• Step 1.2: Add self-contained _memoryLogs array to PlatformServiceMixin
• Step 1.3: Add $appendToMemoryLogs() method to PlatformServiceMixin
• Step 1.4: Update logger.ts to use self-contained memoryLogs
• Step 1.5: Test memoryLogs functionality

Files to Modify:

• src/utils/PlatformServiceMixin.ts
• src/utils/logger.ts

Validation:

• No circular dependency errors
• memoryLogs functionality works correctly
• Linting passes

---

Phase 2: Add Missing Utility Functions (1 hour)

Status: ⏳ PENDING Missing Functions: generateInsertStatement, generateUpdateStatement

Tasks:

• Step 2.1: Add _generateInsertStatement() private method to PlatformServiceMixin
• Step 2.2: Add _generateUpdateStatement() private method to PlatformServiceMixin
• Step 2.3: Add $generateInsertStatement() public wrapper method
• Step 2.4: Add $generateUpdateStatement() public wrapper method
• Step 2.5: Test both utility functions

Files to Modify:

• src/utils/PlatformServiceMixin.ts

Validation:

• Both functions generate correct SQL
• Parameter handling works correctly
• Type safety maintained

---

Phase 3: Update Type Definitions (30 minutes)

Status: ⏳ PENDING Goal: Add new methods to TypeScript interfaces

Tasks:

• Step 3.1: Add new methods to IPlatformServiceMixin interface
• Step 3.2: Add new methods to ComponentCustomProperties interface
• Step 3.3: Verify TypeScript compilation

Files to Modify:

• src/utils/PlatformServiceMixin.ts (interface definitions)

Validation:

• TypeScript compilation passes
• All new methods properly typed
• No type errors in existing code

---

Phase 4: Testing & Validation (1 hour)

Status: ⏳ PENDING Goal: Ensure PlatformServiceMixin is fully functional

Tasks:

• Step 4.1: Create test component to verify all methods
• Step 4.2: Run comprehensive linting
• Step 4.3: Run TypeScript type checking
• Step 4.4: Test caching functionality
• Step 4.5: Test database operations

Validation:

• All tests pass
• No linting errors
• No TypeScript errors
• Caching works correctly
• Database operations work correctly

---

🎯 DAY 2: Migrate All 52 Files (6-8 hours)

Migration Strategy

Priority Order:

1. Views (25 files) - User-facing components
2. Components (15 files) - Reusable UI components
3. Services (8 files) - Business logic
4. Utils (4 files) - Utility functions

Migration Pattern for Each File

// 1. Add PlatformServiceMixin
import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
export default class ComponentName extends Vue {
  mixins = [PlatformServiceMixin];
}

// 2. Replace databaseUtil imports
// Remove: import { ... } from "@/db/databaseUtil";
// Use mixin methods instead

// 3. Update method calls
// Before: generateInsertStatement(contact, 'contacts')
// After:  this.$generateInsertStatement(contact, 'contacts')

Common Replacements

• generateInsertStatement → this.$generateInsertStatement
• generateUpdateStatement → this.$generateUpdateStatement
• parseJsonField → this._parseJsonField
• mapColumnsToValues → this._mapColumnsToValues
• logToDb → this.$log
• logConsoleAndDb → this.$logAndConsole
• memoryLogs → this.$memoryLogs

---

📋 File Migration Checklist

Views (25 files) - Priority 1

Progress: 0/25 (0%)

• QuickActionBvcEndView.vue
• ProjectsView.vue
• ClaimReportCertificateView.vue
• NewEditAccountView.vue
• OnboardMeetingSetupView.vue
• SearchAreaView.vue
• TestView.vue
• InviteOneView.vue
• IdentitySwitcherView.vue
• HelpNotificationsView.vue
• StartView.vue
• OfferDetailsView.vue
• ContactEditView.vue
• SharedPhotoView.vue
• ContactQRScanShowView.vue
• ContactGiftingView.vue
• DiscoverView.vue
• ImportAccountView.vue
• ConfirmGiftView.vue
• SeedBackupView.vue
• ContactAmountsView.vue
• ContactQRScanFullView.vue
• ContactsView.vue
• DIDView.vue
• GiftedDetailsView.vue
• HelpView.vue
• ImportDerivedAccountView.vue
• InviteOneAcceptView.vue
• NewActivityView.vue
• NewEditProjectView.vue
• OnboardMeetingListView.vue
• OnboardMeetingMembersView.vue
• ProjectViewView.vue
• QuickActionBvcBeginView.vue
• RecentOffersToUserProjectsView.vue
• RecentOffersToUserView.vue
• UserProfileView.vue

Components (15 files) - Priority 2

Progress: 3/15 (20%)

• UserNameDialog.vue ✅ MIGRATED
• AmountInput.vue ✅ REVIEWED (no migration needed)
  • Pure UI component, no databaseUtil or notification usage.
• ChoiceButtonDialog.vue
• ContactNameDialog.vue
• DataExportSection.vue
• EntityGrid.vue
• EntityIcon.vue
• EntitySelectionStep.vue
• EntitySummaryButton.vue
• FeedFilters.vue ✅ MIGRATED
• GiftDetailsStep.vue
• GiftedDialog.vue ✅ MIGRATED
• GiftedPrompts.vue
• HiddenDidDialog.vue
• IconRenderer.vue

Services (8 files) - Priority 3

Progress: 0/8 (0%)

• api.ts
• endorserServer.ts
• partnerServer.ts
• deepLinks.ts

Utils (4 files) - Priority 4

Progress: 0/4 (0%)

• LogCollector.ts
• util.ts
• test/index.ts
• PlatformServiceMixin.ts (remove circular dependency)

---

🛠️ Migration Tools

Migration Helper Script

# Track progress
./scripts/migration-helper.sh progress

# Show remaining files
./scripts/migration-helper.sh files

# Show replacement patterns
./scripts/migration-helper.sh patterns

# Show migration template
./scripts/migration-helper.sh template

# Validate migration
./scripts/migration-helper.sh validate

# Show next steps
./scripts/migration-helper.sh next

# Run all checks
./scripts/migration-helper.sh all

Validation Commands

# Check for remaining databaseUtil imports
find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil"

# Run linting
npm run lint

# Run type checking
npx tsc --noEmit

# Count remaining files
find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" | wc -l

---

📊 Progress Tracking

Day 1 Progress

• Phase 1: Circular dependency resolved
• Phase 2: Utility functions added
• Phase 3: Type definitions updated
• Phase 4: Testing completed

Day 2 Progress

• Views migrated (0/25)
• Components migrated (0/15)
• Services migrated (0/8)
• Utils migrated (0/4)
• Validation completed

Overall Progress

• Total files to migrate: 52
• Files migrated: 3
• Progress: 6%

---

🎯 Success Criteria

Day 1 Success Criteria

• PlatformServiceMixin has no circular dependencies
• All utility functions implemented and tested
• Type definitions complete and accurate
• Linting passes with no errors
• TypeScript compilation passes

Day 2 Success Criteria

• 0 files importing databaseUtil
• All 52 files migrated to PlatformServiceMixin
• No runtime errors in migrated components
• All tests passing
• Performance maintained or improved

Overall Success Criteria

• Complete elimination of databaseUtil dependency
• PlatformServiceMixin is the single source of truth for database operations
• Migration fence is fully implemented
• Ready for Phase 3: Cleanup and Optimization

---

🚀 Post-Migration Benefits

1. 80% reduction in database boilerplate code
2. Centralized caching for improved performance
3. Type-safe database operations
4. Eliminated circular dependencies
5. Simplified testing with mockable mixin
6. Consistent error handling across all components
7. Ready for SQLite-only mode

---

📝 Notes & Issues

Current Issues

• None identified yet

Decisions Made

• PlatformServiceMixin approach chosen over USE_DEXIE_DB constant
• Self-contained utility functions preferred over imports
• Priority order: Views → Components → Services → Utils

Lessons Learned

• To be filled as migration progresses

---

🔄 Daily Updates

Day 1 Updates

• Start time: _____
• Phase 1 completion: _____
• Phase 2 completion: _____
• Phase 3 completion: _____
• Phase 4 completion: _____
• End time: _____

Day 2 Updates

• Start time: _____
• Views migration completion: _____
• Components migration completion: _____
• Services migration completion: _____
• Utils migration completion: _____
• Final validation completion: _____
• End time: _____

---

🆘 Contingency Plans

If Day 1 Takes Longer

• Focus on core functionality first
• Defer advanced utility functions to Day 2
• Prioritize circular dependency resolution

If Day 2 Takes Longer

• Focus on high-impact views first
• Batch similar components together
• Use automated scripts for common patterns

If Issues Arise

• Document specific problems in Notes section
• Create targeted fixes
• Maintain backward compatibility during transition

---

🎯 Notification Best Practices and Nuances

• All user-facing notification messages must be defined as constants in src/constants/notifications.ts. Do not hardcode notification strings in components.
• All notification durations/timeouts must use the TIMEOUTS constants from src/utils/notify.ts. Do not hardcode durations.
• Notification helpers (this.notify) must be initialized as a property in created() using createNotifyHelpers(this.$notify).
• Never hardcode notification strings or durations in components.
• When using notifyWhyCannotConfirm or similar utilities, pass a wrapper function if the signature expects a raw notify function (e.g., (msg, timeout) => this.notify.info(msg.text ?? '', timeout)).
• Declare $notify as a property on the class to satisfy the type checker, since Vue injects it at runtime.
• Use type guards or as any for unknown notification payloads when necessary, but prefer type safety where possible.

These practices ensure maintainability, consistency, and type safety for all notification-related code during and after migration.

---

Last Updated: $(date) Next Review: After each phase completion