trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 24 Releases 5 Wiki Activity
Browse Source

docs: add active identity migration implementation and progress tracking 

- Add comprehensive implementation overview document
- Track Phase B component migration progress
- Document migration strategy and architecture decisions
- Include testing and validation procedures

Provides complete documentation for the Active Identity
table separation migration project.
activedid_migration
Matthew Raymer 20 hours ago
parent
09e6a7107a
commit
17951d8cb8
2 changed files with 532 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 347
      doc/active-identity-implementation-overview.md
  2. 185
      doc/active-identity-phase-b-progress.md

347
doc/active-identity-implementation-overview.md
View File

@ -0,0 +1,347 @@
# 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

185
doc/active-identity-phase-b-progress.md
View File

@ -0,0 +1,185 @@
# Active Identity Migration - Phase B Progress
**Author**: Matthew Raymer
**Date**: 2025-08-22T07:05Z
**Status**: 🚧 **IN PROGRESS** - Component Migration Active
## Objective
Complete **Phase B: Component Cutover** by updating all Vue components to use the new Active Identity façade methods instead of directly accessing `settings.activeDid`.
## Current Status
### ✅ **Completed**
- **Migration Infrastructure**: Migrations 003 and 004 implemented
- **Service Façade**: PlatformServiceMixin extended with all required methods
- **TypeScript Types**: Added missing method declarations to Vue component interfaces
- **Feature Flags**: Comprehensive flag system for controlling rollout phases
### 🔄 **In Progress**
- **Component Migration**: Manually updating critical components
- **Pattern Establishment**: Creating consistent migration approach
### ❌ **Pending**
- **Bulk Component Updates**: 40+ components need migration
- **Testing**: Validate migrated components work correctly
- **Performance Validation**: Ensure no performance regressions
## Migration Progress
### **Components Migrated (3/40+)**
| Component | Status | Changes Made | Notes |
|-----------|--------|--------------|-------|
| `IdentitySwitcherView.vue` | ✅ Complete | - Updated `switchIdentity()` method<br>- Added FLAGS import<br>- Uses `$setActiveDid()` | Critical component for identity switching |
| `ImportDerivedAccountView.vue` | ✅ Complete | - Updated `incrementDerivation()` method<br>- Added FLAGS import<br>- Uses `$setActiveDid()` | Handles new account creation |
| `ClaimAddRawView.vue` | ✅ Complete | - Updated `initializeSettings()` method<br>- Uses `$getActiveDid()` | Reads active DID for claims |
### **Components Pending Migration (37+)**
| Component | Usage Pattern | Priority | Estimated Effort |
|-----------|---------------|----------|------------------|
| `HomeView.vue` | ✅ Updated | High | 5 min |
| `ProjectsView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
| `ContactsView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
| `AccountViewView.vue` | `settings.activeDid \|\| ""` | High | 3 min |
| `InviteOneView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
| `TestView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
| `SeedBackupView.vue` | `settings.activeDid \|\| ""` | Medium | 3 min |
| `QuickActionBvcBeginView.vue` | `const activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ConfirmGiftView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ClaimReportCertificateView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ImportAccountView.vue` | `settings.activeDid,` | Medium | 3 min |
| `MembersList.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ShareMyContactInfoView.vue` | `const activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ClaimView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ImageMethodDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `DiscoverView.vue` | `settings.activeDid as string` | Medium | 3 min |
| `QuickActionBvcEndView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ContactQRScanFullView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ContactGiftingView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `OfferDetailsView.vue` | `this.activeDid = settings.activeDid ?? ""` | Medium | 3 min |
| `NewActivityView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `OfferDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `SharedPhotoView.vue` | `this.activeDid = settings.activeDid` | Medium | 3 min |
| `ContactQRScanShowView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `NewEditProjectView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `GiftedDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `HelpView.vue` | `if (settings.activeDid)` | Medium | 3 min |
| `TopMessage.vue` | `settings.activeDid?.slice(11, 15)` | Medium | 3 min |
| `ClaimCertificateView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `UserProfileView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `OnboardingDialog.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `RecentOffersToUserView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `RecentOffersToUserProjectsView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `ContactImportView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
| `GiftedDetailsView.vue` | `this.activeDid = settings.activeDid \|\| ""` | Medium | 3 min |
## Migration Patterns
### **Pattern 1: Simple Read Replacement**
```typescript
// Before
this.activeDid = settings.activeDid || "";
// After
this.activeDid = await this.$getActiveDid() || "";
```
### **Pattern 2: Write Replacement with Dual-Write**
```typescript
// Before
await this.$saveSettings({ activeDid: newDid });
// After
await this.$setActiveDid(newDid);
// Legacy fallback - remove after Phase C
if (!FLAGS.USE_ACTIVE_IDENTITY_ONLY) {
await this.$saveSettings({ activeDid: newDid });
}
```
### **Pattern 3: FLAGS Import Addition**
```typescript
// Add to imports section
import { FLAGS } from "@/config/featureFlags";
```
## Next Steps
### **Immediate Actions (Next 30 minutes)**
1. **Complete High-Priority Components**: Update remaining critical components
2. **Test Migration**: Verify migrated components work correctly
3. **Run Linter**: Check for any remaining TypeScript issues
### **Short Term (Next 2 hours)**
1. **Bulk Migration**: Use automated script for remaining components
2. **Testing**: Validate all migrated components
3. **Performance Check**: Ensure no performance regressions
### **Medium Term (Next 1 day)**
1. **Phase C Preparation**: Enable `USE_ACTIVE_IDENTITY_ONLY` flag
2. **Legacy Fallback Removal**: Remove dual-write patterns
3. **Final Testing**: End-to-end validation
## Success Criteria
### **Phase B Complete When**
- [ ] All 40+ components use new façade methods
- [ ] No direct `settings.activeDid` access remains
- [ ] All components pass linting
- [ ] Basic functionality tested and working
- [ ] Performance maintained or improved
### **Phase C Ready When**
- [ ] All components migrated and tested
- [ ] Feature flag `USE_ACTIVE_IDENTITY_ONLY` can be enabled
- [ ] No legacy fallback usage in production
- [ ] Performance benchmarks show improvement
## Risks & Mitigation
### **High Risk**
- **Component Breakage**: Test each migrated component individually
- **Performance Regression**: Monitor performance metrics during migration
- **TypeScript Errors**: Ensure all method signatures are properly declared
### **Medium Risk**
- **Migration Inconsistency**: Use consistent patterns across all components
- **Testing Coverage**: Ensure comprehensive testing of identity switching flows
### **Low Risk**
- **Backup Size**: Minimal backup strategy for critical files only
- **Rollback Complexity**: Simple git revert if needed
## Tools & Scripts
### **Migration Scripts**
- `scripts/migrate-active-identity-components.sh` - Full backup version
- `scripts/migrate-active-identity-components-efficient.sh` - Minimal backup version
### **Testing Commands**
```bash
# Check for remaining settings.activeDid usage
grep -r "settings\.activeDid" src/views/ src/components/
# Run linter
npm run lint-fix
# Test specific component
npm run test:web -- --grep "IdentitySwitcher"
```
## References
- [Active Identity Implementation Overview](./active-identity-implementation-overview.md)
- [PlatformServiceMixin Documentation](../component-communication-guide.md)
- [Feature Flags Configuration](../feature-flags.md)
- [Database Migration Guide](../database-migration-guide.md)
---
**Status**: Phase B in progress, 3/40+ components migrated
**Next Review**: After completing high-priority components
**Maintainer**: Development team
Write Preview
Loading…
Cancel
Save