forked from jsnbuchanan/crowd-funder-for-time-pwa
docs: reorganize documentation structure with 7-item folder limits
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
This commit is contained in:
Matthew Raymer
189
docs/migration/identity-creation-migration.md
Normal file
189
docs/migration/identity-creation-migration.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Identity Creation Migration
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the migration of automatic identity creation from individual view components to a centralized router navigation guard. This change ensures that user identities are created consistently regardless of entry point, improving the user experience and reducing code duplication.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Previously, automatic identity creation was scattered across multiple view components:
|
||||
- `HomeView.vue` - Primary entry point
|
||||
- `InviteOneAcceptView.vue` - Deep link entry point
|
||||
- `ContactsView.vue` - Contact management
|
||||
- `OnboardMeetingMembersView.vue` - Meeting setup
|
||||
|
||||
This approach had several issues:
|
||||
1. **Inconsistent behavior** - Different entry points could have different identity creation logic
|
||||
2. **Code duplication** - Similar identity creation code repeated across multiple components
|
||||
3. **Race conditions** - Multiple components could attempt identity creation simultaneously
|
||||
4. **Maintenance overhead** - Changes to identity creation required updates in multiple files
|
||||
|
||||
## Solution: Router Navigation Guard
|
||||
|
||||
### Implementation
|
||||
|
||||
The solution moves identity creation to a global router navigation guard in `src/router/index.ts`:
|
||||
|
||||
```typescript
|
||||
router.beforeEach(async (to, from, next) => {
|
||||
try {
|
||||
// Skip identity check for certain routes
|
||||
const skipIdentityRoutes = ['/start', '/new-identifier', '/import-account', '/database-migration'];
|
||||
if (skipIdentityRoutes.includes(to.path)) {
|
||||
return next();
|
||||
}
|
||||
|
||||
// Check if user has any identities
|
||||
const allMyDids = await retrieveAccountDids();
|
||||
|
||||
// Create identity if none exists
|
||||
if (allMyDids.length === 0) {
|
||||
logger.info("[Router] No identities found, creating default seed-based identity");
|
||||
await generateSaveAndActivateIdentity();
|
||||
}
|
||||
|
||||
next();
|
||||
} catch (error) {
|
||||
logger.error("[Router] Identity creation failed:", error);
|
||||
next('/start'); // Redirect to manual identity creation
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Centralized Logic** - All identity creation happens in one place
|
||||
2. **Consistent Behavior** - Same identity creation process regardless of entry point
|
||||
3. **Early Execution** - Identity creation happens before any view loads
|
||||
4. **Error Handling** - Centralized error handling with fallback to manual creation
|
||||
5. **Maintainability** - Single point of change for identity creation logic
|
||||
|
||||
## Migration Details
|
||||
|
||||
### Files Modified
|
||||
|
||||
1. **`src/router/index.ts`**
|
||||
- Added global `beforeEach` navigation guard
|
||||
- Added identity creation logic with error handling
|
||||
- Added route exclusions for manual identity creation
|
||||
|
||||
2. **`src/views/HomeView.vue`**
|
||||
- Removed automatic identity creation logic
|
||||
- Removed `isCreatingIdentifier` state and UI
|
||||
- Simplified `initializeIdentity()` method
|
||||
- Added fallback error handling
|
||||
|
||||
3. **`src/views/InviteOneAcceptView.vue`**
|
||||
- Kept identity creation as fallback for deep links
|
||||
- Added logging for fallback scenarios
|
||||
- Simplified logic since router guard handles most cases
|
||||
|
||||
4. **`src/views/ContactsView.vue`**
|
||||
- Kept identity creation as fallback for invite processing
|
||||
- Added logging for fallback scenarios
|
||||
- Simplified logic since router guard handles most cases
|
||||
|
||||
5. **`src/views/OnboardMeetingMembersView.vue`**
|
||||
- Kept identity creation as fallback for meeting setup
|
||||
- Added logging for fallback scenarios
|
||||
- Simplified logic since router guard handles most cases
|
||||
|
||||
### Route Exclusions
|
||||
|
||||
The following routes are excluded from automatic identity creation:
|
||||
- `/start` - Manual identity creation selection
|
||||
- `/new-identifier` - Manual seed-based identity creation
|
||||
- `/import-account` - Manual account import
|
||||
- `/database-migration` - Database migration process
|
||||
|
||||
### Fallback Strategy
|
||||
|
||||
For deep link scenarios and edge cases, individual views retain minimal identity creation logic as fallbacks:
|
||||
- Only triggers if `activeDid` is missing
|
||||
- Includes logging to identify when fallbacks are used
|
||||
- Maintains backward compatibility
|
||||
|
||||
## Testing Considerations
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **First-time user navigation**
|
||||
- Navigate to any route without existing identity
|
||||
- Verify automatic identity creation
|
||||
- Verify proper navigation to intended route
|
||||
|
||||
2. **Existing user navigation**
|
||||
- Navigate to any route with existing identity
|
||||
- Verify no unnecessary identity creation
|
||||
- Verify normal navigation flow
|
||||
|
||||
3. **Manual identity creation routes**
|
||||
- Navigate to `/start`, `/new-identifier`, `/import-account`
|
||||
- Verify no automatic identity creation
|
||||
- Verify manual creation flow works
|
||||
|
||||
4. **Error scenarios**
|
||||
- Simulate identity creation failure
|
||||
- Verify fallback to `/start` route
|
||||
- Verify error logging
|
||||
|
||||
5. **Deep link scenarios**
|
||||
- Test invite acceptance without existing identity
|
||||
- Verify fallback identity creation works
|
||||
- Verify proper invite processing
|
||||
|
||||
### Performance Impact
|
||||
|
||||
- **Positive**: Reduced code duplication and simplified view logic
|
||||
- **Minimal**: Router guard adds negligible overhead
|
||||
- **Improved**: Consistent identity creation timing
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Privacy Preservation
|
||||
- Identity creation still uses the same secure seed generation
|
||||
- No changes to cryptographic implementation
|
||||
- Maintains user privacy and data sovereignty
|
||||
|
||||
### Error Handling
|
||||
- Centralized error handling prevents identity creation failures from breaking the app
|
||||
- Fallback to manual creation ensures users can always create identities
|
||||
- Proper logging for debugging and monitoring
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
|
||||
1. **Identity Type Selection**
|
||||
- Allow users to choose identity type during automatic creation
|
||||
- Support for different identity creation methods
|
||||
|
||||
2. **Progressive Enhancement**
|
||||
- Add identity creation progress indicators
|
||||
- Improve user feedback during creation process
|
||||
|
||||
3. **Advanced Fallbacks**
|
||||
- Implement more sophisticated fallback strategies
|
||||
- Add retry logic for failed identity creation
|
||||
|
||||
4. **Analytics Integration**
|
||||
- Track identity creation success rates
|
||||
- Monitor fallback usage patterns
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues arise, the migration can be rolled back by:
|
||||
|
||||
1. Removing the router navigation guard from `src/router/index.ts`
|
||||
2. Restoring automatic identity creation in individual views
|
||||
3. Reverting to the previous implementation pattern
|
||||
|
||||
## Conclusion
|
||||
|
||||
This migration successfully centralizes identity creation logic while maintaining backward compatibility and improving the overall user experience. The router navigation guard approach provides a robust, maintainable solution that ensures consistent identity creation across all entry points.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Database Migration Guide](../doc/database-migration-guide.md)
|
||||
- [Migration Progress Tracker](../doc/migration-progress-tracker.md)
|
||||
- [Platform Service Architecture](../doc/platformservicemixin-completion-plan.md)
|
||||
Reference in New Issue
Block a user