crowd-funder-for-time-pwa/doc/active-identity-implementation-overview.md

# Active Identity Implementation Overview

**Author**: Matthew Raymer
**Date**: 2025-08-21T13:40Z
**Status**: 🚧 **IN PROGRESS** - Implementation Complete, Testing Pending

## Objective

Separate the `activeDid` field from the monolithic `settings` table into a
dedicated `active_identity` table to achieve:

- **Data normalization** and reduced cache drift
- **Simplified identity management** with dedicated table
- **Zero breaking API surface** for existing components
- **Phased migration** with rollback capability

## Result

This document provides a comprehensive overview of the implemented Active
Identity table separation system, including architecture, migration strategy,
and component integration.

## Use/Run

The implementation is ready for testing. Components can immediately use the new
façade methods while maintaining backward compatibility through dual-write
triggers.

## Context & Scope

- **Audience**: Developers working with identity management and database
  migrations
- **In scope**: Active DID management, database schema evolution, Vue component
  integration
- **Out of scope**: Multi-profile support beyond basic scope framework, complex
  identity hierarchies

## Artifacts & Links

- **Implementation**: `src/db/tables/activeIdentity.ts`,
  `src/utils/PlatformServiceMixin.ts`
- **Migrations**: `src/db-sql/migration.ts` (migrations 003 & 004)
- **Configuration**: `src/config/featureFlags.ts`
- **Documentation**: This document and progress tracking

## Environment & Preconditions

- **Database**: SQLite (Absurd-SQL for Web, Capacitor SQLite for Mobile)
- **Framework**: Vue.js with PlatformServiceMixin
- **Migration System**: Built-in migrationService.ts with automatic execution

## Architecture / Process Overview

The Active Identity separation follows a **phased migration pattern** with
dual-write triggers to ensure zero downtime and backward compatibility.

```mermaid
flowchart TD
    A[Legacy State] --> B[Phase A: Dual-Write]
    B --> C[Phase B: Component Cutover]
    C --> D[Phase C: Legacy Cleanup]

    A --> A1[settings.activeDid]
    B --> B1[active_identity table]
    B --> B2[Dual-write trigger]
    B --> B3[Fallback support]
    C --> C1[Components use façade]
    C --> C2[Legacy fallback disabled]
    D --> D1[Drop activeDid column]
    D --> D2[Remove triggers]
```

## Interfaces & Contracts

### Database Schema

| Table | Purpose | Key Fields | Constraints |
|-------|---------|------------|-------------|
| `active_identity` | Store active DID per scope | `scope`, `active_did`, | Unique scope, FK to accounts.did |
| | | `updated_at` | |
| `settings` | User preferences (legacy) | `id`, `accountDid`, `apiServer`, | `activeDid` removed in Phase C |
| | | etc. | |

### Service Façade API

| Method | Purpose | Parameters | Returns |
|--------|---------|------------|---------|
| `$getActiveDid(scope?)` | Retrieve active DID | `scope` (default: | `Promise<string \| null>` |
| | | 'default') | |
| `$setActiveDid(did, scope?)` | Set active DID | `did`, `scope` (default: | `Promise<void>` |
| | | 'default') | |
| `$switchActiveIdentity(did)` | Switch to different DID | `did` | `Promise<void>` |
| `$getActiveIdentityScopes()` | Get available scopes | None | `Promise<string[]>` |

## Repro: End-to-End Procedure

### 1. Database Migration Execution

```bash
# Migrations run automatically on app startup
# Migration 003: Creates active_identity table
# Migration 004: Drops settings.activeDid column (Phase C)
```

### 2. Component Usage

```typescript
// Before (legacy)
const activeDid = settings.activeDid || "";
await this.$saveSettings({ activeDid: newDid });

// After (new façade)
const activeDid = await this.$getActiveDid() || "";
await this.$setActiveDid(newDid);
```

### 3. Feature Flag Control

```typescript
// Enable/disable migration phases
FLAGS.USE_ACTIVE_IDENTITY_ONLY = false;      // Allow legacy fallback
FLAGS.DROP_SETTINGS_ACTIVEDID = false;       // Keep legacy column
FLAGS.LOG_ACTIVE_ID_FALLBACK = true;         // Log fallback usage
```

## What Works (Evidence)

- ✅ **Migration Infrastructure**: Migrations 003 and 004 integrated into
  `migrationService.ts`
- ✅ **Table Creation**: `active_identity` table schema with proper constraints
  and indexes
- ✅ **Service Façade**: PlatformServiceMixin extended with all required methods
- ✅ **Feature Flags**: Comprehensive flag system for controlling rollout phases
- ✅ **Dual-Write Support**: One-way trigger from `settings.activeDid` →
  `active_identity.active_did`
- ✅ **Validation**: DID existence validation before setting as active
- ✅ **Error Handling**: Comprehensive error handling with logging

## What Doesn't (Evidence & Hypotheses)

- ❌ **Component Migration**: No components yet updated to use new façade
  methods
- ❌ **Testing**: No automated tests for new functionality
- ❌ **Performance Validation**: No benchmarks for read/write performance
- ❌ **Cross-Platform Validation**: Not tested on mobile platforms yet

## Risks, Limits, Assumptions

### **Migration Risks**

- **Data Loss**: If migration fails mid-process, could lose active DID state
- **Rollback Complexity**: Phase C (column drop) requires table rebuild, not
  easily reversible
- **Trigger Dependencies**: Dual-write trigger could fail if `active_identity`
  table is corrupted

### **Performance Limits**

- **Dual-Write Overhead**: Each `activeDid` change triggers additional
  database operations
- **Fallback Queries**: Legacy fallback requires additional database queries
- **Transaction Scope**: Active DID changes wrapped in transactions for
  consistency

### **Security Boundaries**

- **DID Validation**: Only validates DID exists in accounts table, not
  ownership
- **Scope Isolation**: No current scope separation enforcement beyond table
  constraints
- **Access Control**: No row-level security on `active_identity` table

## Next Steps

| Owner | Task | Exit Criteria | Target Date (UTC) |
|-------|------|---------------|-------------------|
| Developer | Test migrations | Migrations execute without errors | 2025-08-21 |
| Developer | Update components | All components use new façade | 2025-08-22 |
| | | methods | |
| Developer | Performance testing | Read/write performance meets | 2025-08-23 |
| | | requirements | |
| Developer | Phase C activation | Feature flag enables column | 2025-08-24 |
| | | removal | |

## References

- [Database Migration Guide](../database-migration-guide.md)
- [PlatformServiceMixin Documentation](../component-communication-guide.md)
- [Feature Flags Configuration](../feature-flags.md)

## Competence Hooks

- **Why this works**: Phased migration with dual-write triggers ensures zero
  downtime while maintaining data consistency through foreign key constraints
  and validation
- **Common pitfalls**: Forgetting to update components before enabling
  `USE_ACTIVE_IDENTITY_ONLY`, not testing rollback scenarios, ignoring
  cross-platform compatibility
- **Next skill unlock**: Implement automated component migration using codemods
  and ESLint rules
- **Teach-back**: Explain how the dual-write trigger prevents data divergence
  during the transition phase

## Collaboration Hooks

- **Reviewers**: Database team for migration logic, Vue team for component
  integration, DevOps for deployment strategy
- **Sign-off checklist**: Migrations tested in staging, components updated,
  performance validated, rollback plan documented

## Assumptions & Limits

- **Single User Focus**: Current implementation assumes single-user mode with
  'default' scope
- **Vue Compatibility**: Assumes `vue-facing-decorator` compatibility (needs
  validation)
- **Migration Timing**: Assumes migrations run on app startup (automatic
  execution)
- **Platform Support**: Assumes same behavior across Web (Absurd-SQL) and
  Mobile (Capacitor SQLite)

## Implementation Details

### **Migration 003: Table Creation**

Creates the `active_identity` table with:

- **Primary Key**: Auto-incrementing ID
- **Scope Field**: For future multi-profile support (currently 'default')
- **Active DID**: Foreign key to accounts.did with CASCADE UPDATE
- **Timestamps**: ISO format timestamps for audit trail
- **Indexes**: Performance optimization for scope and DID lookups

### **Migration 004: Column Removal**

Implements Phase C by:

- **Table Rebuild**: Creates new settings table without activeDid column
- **Data Preservation**: Copies all other data from legacy table
- **Index Recreation**: Rebuilds necessary indexes
- **Trigger Cleanup**: Removes dual-write triggers

### **Service Façade Implementation**

The PlatformServiceMixin extension provides:

- **Dual-Read Logic**: Prefers new table, falls back to legacy during
  transition
- **Dual-Write Logic**: Updates both tables during Phase A/B
- **Validation**: Ensures DID exists before setting as active
- **Transaction Safety**: Wraps operations in database transactions
- **Error Handling**: Comprehensive logging and error propagation

### **Feature Flag System**

Controls migration phases through:

- **`USE_ACTIVE_IDENTITY_ONLY`**: Disables legacy fallback reads
- **`DROP_SETTINGS_ACTIVEDID`**: Enables Phase C column removal
- **`LOG_ACTIVE_ID_FALLBACK`**: Logs when legacy fallback is used
- **`ENABLE_ACTIVE_IDENTITY_MIGRATION`**: Master switch for migration
  system

## Security Considerations

### **Data Validation**

- DID format validation (basic "did:" prefix check)
- Foreign key constraints ensure referential integrity
- Transaction wrapping prevents partial updates

### **Access Control**

- No row-level security implemented
- Scope isolation framework in place for future use
- Validation prevents setting non-existent DIDs as active

### **Audit Trail**

- Timestamps on all active identity changes
- Logging of fallback usage and errors
- Migration tracking through built-in system

## Performance Characteristics

### **Read Operations**

- **Primary Path**: Single query to `active_identity` table
- **Fallback Path**: Additional query to `settings` table (Phase A only)
- **Indexed Fields**: Both scope and active_did are indexed

### **Write Operations**

- **Dual-Write**: Updates both tables during transition (Phase A/B)
- **Transaction Overhead**: All operations wrapped in transactions
- **Trigger Execution**: Additional database operations per update

### **Migration Impact**

- **Table Creation**: Minimal impact (runs once)
- **Column Removal**: Moderate impact (table rebuild required)
- **Data Seeding**: Depends on existing data volume

## Testing Strategy

### **Unit Testing**

- Service façade method validation
- Error handling and edge cases
- Transaction rollback scenarios

### **Integration Testing**

- Migration execution and rollback
- Cross-platform compatibility
- Performance under load

### **End-to-End Testing**

- Component integration
- User workflow validation
- Migration scenarios

## Deployment Considerations

### **Rollout Strategy**

- **Phase A**: Deploy with dual-write enabled
- **Phase B**: Update components to use new methods
- **Phase C**: Enable column removal (irreversible)

### **Rollback Plan**

- **Phase A/B**: Disable feature flags, revert to legacy methods
- **Phase C**: Requires database restore (no automatic rollback)

### **Monitoring**

- Track fallback usage through logging
- Monitor migration success rates
- Alert on validation failures

---

**Status**: Implementation complete, ready for testing and component migration
**Next Review**: After initial testing and component updates
**Maintainer**: Development team