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

```typescript
// 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

```typescript
// 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)
```typescript
// 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)
```typescript
// 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

```typescript
// 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
```typescript
// 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
```typescript
// 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
```json
{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "patterns": [
          {
            "group": ["../db/index"],
            "message": "Use PlatformServiceMixin instead of direct Dexie access"
          }
        ]
      }
    ]
  }
}
```

#### TypeScript Rules
```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}
```

### 2. Runtime Checks

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

#### Production Safety
```typescript
// 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
- [x] PlatformServiceMixin implementation
- [x] SQLite database service
- [x] Migration tools
- [x] Settings migration
- [x] Account migration
- [x] 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