crowd-funder-for-time-pwa/doc/migration-fence-definition.md

Migration Fence Definition: Dexie to SQLite

Overview

This document defines the migration fence - the boundary between the legacy Dexie (IndexedDB) storage system and the new SQLite-based storage system in TimeSafari. The fence ensures controlled migration while maintaining data integrity and application stability.

⚠️ UPDATE: The migration fence is now implemented through the PlatformServiceMixin rather than a USE_DEXIE_DB constant. This provides a cleaner, more maintainable approach to database access control.

Current Migration Status

✅ Completed Components

• SQLite Database Service: Fully implemented with absurd-sql
• Platform Service Layer: Unified database interface across platforms
• PlatformServiceMixin: Centralized database access with caching and utilities
• Migration Tools: Data comparison and transfer utilities
• Schema Migration: Complete table structure migration
• Data Export/Import: Backup and restore functionality

🔄 Active Migration Components

• Settings Migration: Core user settings transferred
• Account Migration: Identity and key management
• Contact Migration: User contact data (via import interface)
• DatabaseUtil Migration: Moving functions to PlatformServiceMixin

❌ Legacy Components (Fence Boundary)

• Dexie Database: Legacy IndexedDB storage (disabled by default)
• Dexie-Specific Code: Direct database access patterns
• Legacy Migration Paths: Old data transfer methods

Migration Fence Definition

1. PlatformServiceMixin Boundary

// src/utils/PlatformServiceMixin.ts
export const PlatformServiceMixin = {
  computed: {
    platformService(): PlatformService {
      // FENCE: All database operations go through platform service
      // No direct Dexie access outside migration tools
      return PlatformServiceFactory.getInstance();
    }
  }
}

Fence Rule: All database operations must use:

• this.$db() for read operations
• this.$exec() for write operations
• this.$settings() for settings access
• this.$contacts() for contact access
• No direct db. or accountsDBPromise access in application code

2. Service Layer Boundary

// src/services/PlatformServiceFactory.ts
export class PlatformServiceFactory {
  public static getInstance(): PlatformService {
    // FENCE: All database operations go through platform service
    // No direct Dexie access outside migration tools
  }
}

Fence Rule: All database operations must use:

• PlatformService.dbQuery() for read operations
• PlatformService.dbExec() for write operations
• No direct db. or accountsDBPromise access in application code

3. Data Access Patterns

✅ Allowed (Inside Fence)

// Use PlatformServiceMixin for all database operations
const contacts = await this.$contacts();
const settings = await this.$settings();
const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDid]);

❌ Forbidden (Outside Fence)

// Direct Dexie access (legacy pattern)
const contacts = await db.contacts.where('did').equals(accountDid).toArray();

// Direct database reference
const result = await accountsDBPromise;

4. Migration Tool Boundary

// src/services/indexedDBMigrationService.ts
// FENCE: Only migration tools can access both databases
export async function compareDatabases(): Promise<DataComparison> {
  // This is the ONLY place where both databases are accessed
}

Fence Rule: Migration tools are the exclusive interface between:

• Legacy Dexie database
• New SQLite database
• Data comparison and transfer operations

Migration Fence Guidelines

1. Code Development Rules

New Feature Development

• Always use PlatformServiceMixin for database operations
• Never import or reference Dexie directly
• Always use mixin methods like this.$settings(), this.$contacts()

Legacy Code Maintenance

• Only modify Dexie code for migration purposes
• Always add migration tests for schema changes
• Never add new Dexie-specific features

2. Data Integrity Rules

Migration Safety

• Always create backups before migration
• Always verify data integrity after migration
• Never delete legacy data until verified

Rollback Strategy

• Always maintain ability to rollback to Dexie
• Always preserve migration logs
• Never assume migration is irreversible

3. Testing Requirements

Migration Testing

// Required test pattern for migration
describe('Database Migration', () => {
  it('should migrate data without loss', async () => {
    // 1. Create test data in Dexie
    // 2. Run migration
    // 3. Verify data integrity in SQLite
    // 4. Verify PlatformServiceMixin access
  });
});

Application Testing

// Required test pattern for application features
describe('Feature with Database', () => {
  it('should work with PlatformServiceMixin', async () => {
    // Test with PlatformServiceMixin methods
    // Verify all operations use mixin methods
  });
});

Migration Fence Enforcement

1. Static Analysis

ESLint Rules

{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "patterns": [
          {
            "group": ["../db/index"],
            "message": "Use PlatformServiceMixin instead of direct Dexie access"
          }
        ]
      }
    ]
  }
}

TypeScript Rules

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}

2. Runtime Checks

Development Mode Validation

// Development-only fence validation
if (import.meta.env.DEV) {
  console.warn('⚠️ Using PlatformServiceMixin for all database operations');
}

Production Safety

// Production fence enforcement
if (import.meta.env.PROD) {
  // All database operations must go through PlatformServiceMixin
  // Direct Dexie access is not allowed
}

Migration Status Checklist

✅ Completed

• PlatformServiceMixin implementation
• SQLite database service
• Migration tools
• Settings migration
• Account migration
• ActiveDid migration

🔄 In Progress

• Contact migration
• DatabaseUtil to PlatformServiceMixin migration
• File-by-file migration

❌ Not Started

• Legacy Dexie removal
• Final cleanup and validation

Benefits of PlatformServiceMixin Approach

1. Centralized Access: Single point of control for all database operations
2. Caching: Built-in caching for performance optimization
3. Type Safety: Enhanced TypeScript integration
4. Error Handling: Consistent error handling across components
5. Code Reduction: Up to 80% reduction in database boilerplate
6. Maintainability: Single source of truth for database patterns

---

Author: Matthew Raymer Created: 2025-07-05 Status: Active Migration Phase Last Updated: 2025-07-05 Note: Migration fence now implemented through PlatformServiceMixin instead of USE_DEXIE_DB constant