18 KiB

Raw Blame History

ActiveDid Migration Plan - Implementation Guide

Author: Matthew Raymer Date: 2025-09-03T06:40:54Z Status: 🚀 ACTIVE MIGRATION - API Layer Complete, Component Updates In Progress

Objective

Move the activeDid field from the settings table to a dedicated active_identity table to improve database architecture, prevent data corruption, and separate identity selection from user preferences.

Result

This document provides the specific implementation steps required to complete the ActiveDid migration with all necessary code changes.

Use/Run

Follow this implementation checklist step-by-step to complete the migration.

Context & Scope

In scope: Database migration, API updates, component updates, testing
Out of scope: UI changes, authentication flow changes, MASTER_SETTINGS_KEY elimination (future improvement)

Critical Vue Reactivity Bug Discovery

Issue

During testing of the ActiveDid migration, a critical Vue reactivity bug was discovered:

Problem: The newDirectOffersActivityNumber element in HomeView.vue fails to render correctly without a watcher on numNewOffersToUser.

Symptoms:

Element not found in DOM even when numNewOffersToUser has correct value
Test failures with "element not found" errors
Inconsistent rendering behavior

Root Cause: Unknown Vue reactivity issue where property changes don't trigger proper template updates

Workaround: A watcher on numNewOffersToUser with debug logging is required:

@Watch("numNewOffersToUser")
onNumNewOffersToUserChange(newValue: number, oldValue: number) {
  logger.debug("[HomeView] numNewOffersToUser changed", {
    oldValue,
    newValue,
    willRender: !!newValue,
    timestamp: new Date().toISOString()
  });
}

Impact: This watcher must remain in the codebase until the underlying Vue reactivity issue is resolved.

Files Affected: src/views/HomeView.vue

Investigation Needed

Investigate why Vue reactivity is not working correctly
Check for race conditions in component lifecycle
Verify if this affects other components
Consider Vue version upgrade or configuration changes

Implementation Checklist

Phase 1: Database Migration ✅ COMPLETE

Add migration to MIGRATIONS array in src/db-sql/migration.ts
Create active_identity table with constraints
Include data migration from settings to active_identity table

Status: All migrations executed successfully. active_identity table created and populated with data.

Phase 2: API Layer Updates ✅ COMPLETE

Implement $getActiveIdentity() method (exists with correct return type)
Fix $getActiveIdentity() return type to match documented interface
Update $accountSettings() to use new method (minimal safe change)
Update $updateActiveDid() with dual-write pattern
Add strategic logging for migration verification

Status: All API layer updates complete and verified working. Methods return correct data format and maintain backward compatibility.

Phase 3: Component Updates 🟡 IN PROGRESS

Update HomeView.vue to use $getActiveIdentity() (completed)
Update 32 remaining components to use $getActiveIdentity()
Replace this.activeDid = settings.activeDid pattern
Test each component individually

Status: HomeView.vue successfully migrated. 32 components remaining. API layer ready for systematic updates.

Phase 4: Testing 🟡 PARTIALLY STARTED

Test Web platform (verified working)
Test Electron platform
Test iOS platform
Test Android platform
Test migration rollback scenarios
Test data corruption recovery

Required Code Changes

1. Database Migration ✅ COMPLETE

// Already added to MIGRATIONS array in src/db-sql/migration.ts
{
  name: "003_active_did_separate_table",
  sql: `
    -- Create new active_identity table with proper constraints
    CREATE TABLE IF NOT EXISTS active_identity (
      id INTEGER PRIMARY KEY CHECK (id = 1),
      activeDid TEXT NOT NULL,
      lastUpdated TEXT NOT NULL DEFAULT (datetime('now')),
      FOREIGN KEY (activeDid) REFERENCES accounts(did) ON DELETE CASCADE
    );

    -- Add performance indexes
    CREATE INDEX IF NOT EXISTS idx_active_identity_activeDid ON active_identity(activeDid);
    CREATE UNIQUE INDEX IF NOT EXISTS idx_active_identity_single_record ON active_identity(id);

    -- Insert default record (will be updated during migration)
    INSERT OR IGNORE INTO active_identity (id, activeDid, lastUpdated) VALUES (1, '', datetime('now'));

    -- MIGRATE EXISTING DATA: Copy activeDid from settings to active_identity
    -- This prevents data loss when migration runs on existing databases
    UPDATE active_identity 
    SET activeDid = (SELECT activeDid FROM settings WHERE id = 1), 
        lastUpdated = datetime('now')
    WHERE id = 1 
    AND EXISTS (SELECT 1 FROM settings WHERE id = 1 AND activeDid IS NOT NULL AND activeDid != '');
  `,
},

2. $getActiveIdentity() Method ✅ EXISTS

// Already exists in PlatformServiceMixin.ts with correct return type
async $getActiveIdentity(): Promise<{ activeDid: string }> {
  try {
    const result = await this.$dbQuery(
      "SELECT activeDid FROM active_identity WHERE id = 1"
    );
    
    if (result?.values?.length) {
      const activeDid = result.values[0][0] as string;
      
      // Validate activeDid exists in accounts
      if (activeDid) {
        const accountExists = await this.$dbQuery(
          "SELECT did FROM accounts WHERE did = ?",
          [activeDid]
        );
        
        if (accountExists?.values?.length) {
          return { activeDid };
        } else {
          // Clear corrupted activeDid
          await this.$dbExec(
            "UPDATE active_identity SET activeDid = '', lastUpdated = datetime('now') WHERE id = 1"
          );
          return { activeDid: "" };
        }
      }
    }
    
    return { activeDid: "" };
  } catch (error) {
    logger.error("[PlatformServiceMixin] Error getting active identity:", error);
    return { activeDid: "" };
  }
}

3. Update $accountSettings Method

// Update in PlatformServiceMixin.ts
async $accountSettings(did?: string, defaults: Settings = {}): Promise<Settings> {
  try {
    // Get settings without activeDid (unchanged logic)
    const settings = await this.$getMasterSettings(defaults);

    if (!settings) {
      return defaults;
    }

    // Get activeDid from new table (new logic)
    const activeIdentity = await this.$getActiveIdentity();

    // Return combined result (maintains backward compatibility)
    return { ...settings, activeDid: activeIdentity.activeDid };
  } catch (error) {
    logger.error("[Settings Trace] ❌ Error in $accountSettings:", error);
    return defaults;
  }
}

4. Update $updateActiveDid Method

// Update in PlatformServiceMixin.ts
async $updateActiveDid(newDid: string | null): Promise<boolean> {
  try {
    if (newDid === null) {
      // Clear active identity in both tables
      await this.$dbExec(
        "UPDATE active_identity SET activeDid = '', lastUpdated = datetime('now') WHERE id = 1"
      );
      
      // Keep legacy field in sync (backward compatibility)
      await this.$dbExec(
        "UPDATE settings SET activeDid = '' WHERE id = ?",
        [MASTER_SETTINGS_KEY]
      );
    } else {
      // Validate DID exists before setting
      const accountExists = await this.$dbQuery(
        "SELECT did FROM accounts WHERE did = ?",
        [newDid]
      );

      if (!accountExists?.values?.length) {
        logger.error(`[PlatformServiceMixin] Cannot set activeDid to non-existent DID: ${newDid}`);
        return false;
      }

      // Update active identity in new table
      await this.$dbExec(
        "UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
        [newDid]
      );
      
      // Keep legacy field in sync (backward compatibility)
      await this.$dbExec(
        "UPDATE settings SET activeDid = ? WHERE id = ?",
        [newDid, MASTER_SETTINGS_KEY]
      );
    }

    // Update internal tracking
    await this._updateInternalActiveDid(newDid);
    return true;
  } catch (error) {
    logger.error("[PlatformServiceMixin] Error updating activeDid:", error);
    return false;
  }
}

5. Component Updates Required

35 components need this pattern change:

// CURRENT PATTERN (replace in all components):
this.activeDid = settings.activeDid || "";

// NEW PATTERN (use in all components):
const activeIdentity = await this.$getActiveIdentity();
this.activeDid = activeIdentity.activeDid || "";

Components requiring updates:

Views (28 components)

src/views/DIDView.vue (line 378)
src/views/TestView.vue (line 654)
src/views/ContactAmountsView.vue (line 226)
src/views/HomeView.vue (line 517)
src/views/UserProfileView.vue (line 185)
src/views/ClaimView.vue (line 730)
src/views/OfferDetailsView.vue (line 435)
src/views/QuickActionBvcEndView.vue (line 229)
src/views/SharedPhotoView.vue (line 178)
src/views/ClaimReportCertificateView.vue (line 56)
src/views/ProjectsView.vue (line 393)
src/views/ClaimAddRawView.vue (line 114)
src/views/ContactQRScanShowView.vue (line 288)
src/views/InviteOneAcceptView.vue (line 122)
src/views/RecentOffersToUserView.vue (line 118)
src/views/NewEditProjectView.vue (line 380)
src/views/GiftedDetailsView.vue (line 443)
src/views/ProjectViewView.vue (line 782)
src/views/ContactsView.vue (line 296)
src/views/ContactQRScanFullView.vue (line 267)
src/views/NewActivityView.vue (line 204)
src/views/ClaimCertificateView.vue (line 42)
src/views/ContactGiftingView.vue (line 166)
src/views/RecentOffersToUserProjectsView.vue (line 126)
src/views/InviteOneView.vue (line 285)
src/views/IdentitySwitcherView.vue (line 202)
src/views/AccountViewView.vue (line 1052)
src/views/ConfirmGiftView.vue (line 549)
src/views/ContactImportView.vue (line 342)

Components (7 components)

src/components/OfferDialog.vue (line 177)
src/components/PhotoDialog.vue (line 270)
src/components/GiftedDialog.vue (line 223)
src/components/MembersList.vue (line 234)
src/components/OnboardingDialog.vue (line 272)
src/components/ImageMethodDialog.vue (line 502)
src/components/FeedFilters.vue (line 89)

Implementation Strategy:

Systematic Replacement: Use grep search to find all instances
Pattern Matching: Replace this.activeDid = settings.activeDid with new pattern
Error Handling: Ensure proper error handling in each component
Testing: Test each component individually after update

Example Component Update:

// BEFORE (in any component):
private async initializeSettings() {
  const settings = await this.$accountSettings();
  this.activeDid = settings.activeDid || "";
  this.apiServer = settings.apiServer || "";
}

// AFTER (in any component):
private async initializeSettings() {
  const settings = await this.$accountSettings();
  const activeIdentity = await this.$getActiveIdentity();
  this.activeDid = activeIdentity.activeDid || "";
  this.apiServer = settings.apiServer || "";
}

Alternative Pattern (if settings still needed):

// If component needs both settings and activeDid:
private async initializeSettings() {
  const settings = await this.$accountSettings();
  const activeIdentity = await this.$getActiveIdentity();
  
  // Use activeDid from new table
  this.activeDid = activeIdentity.activeDid || "";
  
  // Use other settings from settings table
  this.apiServer = settings.apiServer || "";
  this.partnerApiServer = settings.partnerApiServer || "";
  // ... other settings
}

What Works (Evidence)

✅ Migration code exists in MIGRATIONS array
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows successful execution of migrations 003 and 004
- Verify at: 🎉 [Migration] Successfully applied: 003_active_did_separate_table
✅ $getActiveIdentity() method exists in PlatformServiceMixin
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows method calls returning correct data format
- Verify at: [PlatformServiceMixin] $getActiveIdentity(): activeDid resolved {activeDid: 'did:ethr:0xAe6ea6A4c20aDeE7B1c7Ee1fEFAa6fBe0986a671'}
✅ Database migration infrastructure exists and mature
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows 6 migrations applied successfully
- Verify at: 🎉 [Migration] Migration process complete! Summary: 6 applied, 0 skipped
✅ $accountSettings() updated with minimal safe change
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows method returning activeDid from new table
- Status: Maintains all existing complex logic while using new table as primary source
✅ $updateActiveDid() dual-write implemented
- Time: 2025-09-03T06:40:54Z
- Evidence: Method exists and ready for testing
- Status: Uses MASTER_SETTINGS_KEY constant for proper settings table targeting
✅ HomeView.vue successfully migrated to use new API
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows [HomeView] ActiveDid migration - using new API
- Status: Component successfully uses $getActiveIdentity() instead of settings.activeDid
✅ Clean architecture implemented - active_identity is now single source of truth
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows consistent activeDid values from active_identity table
- Status: active_identity table is the only source for activeDid, settings table handles app config only
✅ Schema cleanup - activeDid column removed from settings table
- Time: 2025-09-03T06:40:54Z
- Evidence: Console log shows successful execution of migration 004
- Status: Complete separation of concerns - no more confusing dual-purpose columns

What Doesn't (Evidence & Hypotheses)

❌ 32 components still use old pattern this.activeDid = settings.activeDid
- Time: 2025-09-03T06:40:54Z
- Evidence: Grep search found 32 remaining instances across views and components
- Hypothesis: Components need updates but API layer is now ready
- Next probe: Systematic component updates can now proceed

Risks, Limits, Assumptions

Data Loss Risk: Migration failure could lose activeDid values
Breaking Changes: API updates required in PlatformServiceMixin
Testing Overhead: All platforms must be tested with new structure
Component Updates: 35+ components need individual updates and testing

Rollback Strategy

Schema Rollback

-- If migration fails, restore original schema
DROP TABLE IF EXISTS active_identity;

Data Rollback

// Rollback function to restore activeDid to settings table
async function rollbackActiveDidMigration(): Promise<boolean> {
  try {
    const activeIdentityResult = await dbQuery(
      "SELECT activeDid FROM active_identity WHERE id = 1"
    );
    
    if (activeIdentityResult?.values?.length) {
      const activeDid = activeIdentityResult.values[0][0] as string;
      
      await dbExec(
        "UPDATE settings SET activeDid = ? WHERE id = ?",
        [activeDid, MASTER_SETTINGS_KEY]
      );
      
      return true;
    }
    
    return false;
  } catch (error) {
    logger.error("[Rollback] Failed to restore activeDid:", error);
    return false;
  }
}

Next Steps

Task	Exit Criteria	Priority
Update $accountSettings() method	Method calls $getActiveIdentity and combines with settings	✅ COMPLETE
Implement $updateActiveDid() dual-write	Method updates both active_identity and settings tables	✅ COMPLETE
Start application in browser	Application loads and initializes IndexedDB database	✅ COMPLETE
Inspect IndexedDB via DevTools	Verify active_identity table exists and contains data	✅ COMPLETE
Update first component	One component successfully uses new API pattern	✅ COMPLETE (HomeView.vue)
Systematic component updates	All 32 remaining components use new API pattern	🟢 HIGH
Test all platforms	Web, Electron, iOS, Android platforms verified working	🟡 MEDIUM
Performance optimization	Reduce excessive $getActiveIdentity() calls	🟡 MEDIUM

Critical Blocker: API layer complete. Ready to proceed with component updates.

Performance Observations

Excessive API Calls Detected

The console log shows $getActiveIdentity() being called very frequently (multiple times per component mount). This suggests:

Components may be calling the API more than necessary
Could be optimized for better performance
Not a blocker, but worth monitoring during component updates

Recommended Optimization Strategy

Audit component lifecycle - Ensure API calls happen only when needed
Implement caching - Consider short-term caching of activeDid values
Batch updates - Group related API calls where possible
Monitor performance - Track API call frequency during component updates

Future Improvement: MASTER_SETTINGS_KEY Elimination

Not critical for this task but logged for future improvement:

// Current: WHERE id = "1" 
// Future: WHERE accountDid IS NULL

// This eliminates the confusing concept of "master" settings
// and uses a cleaner pattern for default settings

References

Competence Hooks

Why this works: Separates concerns between identity selection and user preferences, prevents data corruption with foreign key constraints
Common pitfalls: Method signature mismatches, forgetting dual-write pattern, not testing database state
Next skill unlock: Systematic API updates with backward compatibility
Teach-back: Explain why dual-write pattern is needed during migration transition

Collaboration Hooks

Reviewers: Database team, PlatformServiceMixin maintainers, QA team
Sign-off checklist:
- Migration script integrated with existing MIGRATIONS array
- $getActiveIdentity() method returns correct type
- $accountSettings() method updated to use new API (minimal safe change)
- $updateActiveDid() method implements dual-write pattern
- All 35+ components updated to use new API
- Rollback procedures validated
- All platforms tested
- All stakeholders approve deployment timeline

18 KiB Raw Blame History