trentlarson/crowd-funder-from-jason
1
0
Fork 0
forked from jsnbuchanan/crowd-funder-for-time-pwa
Code Issues Pull Requests Projects Releases Wiki Activity

docs: comprehensive documentation updates and modernization

Browse Source 
- Update BUILDING.md with current build system information
- Modernize various README files across the project
- Update CHANGELOG.md with recent changes
- Improve documentation consistency and formatting
- Update platform-specific documentation (iOS, Electron, Docker)
- Enhance test documentation and build guides
This commit is contained in:
Matthew Raymer
2025-08-20 13:02:01 +00:00
parent 963ff9234f
commit 2d17bfd3b4
43 changed files with 1022 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/DEEP_LINKS.md
View File

@@ -47,6 +47,7 @@ type ClaimParams = z.infer<typeof claimSchema>;
### Type Safety Layers
1. **Schema Definition**
```typescript
// src/interfaces/deepLinks.ts
export const deepLinkSchemas = {
@@ -59,6 +60,7 @@ type ClaimParams = z.infer<typeof claimSchema>;
```
2. **Type Generation**
```typescript
// Types are automatically generated from schemas
export type DeepLinkParams = {
@@ -67,6 +69,7 @@ type ClaimParams = z.infer<typeof claimSchema>;
```
3. **Runtime Validation**
```typescript
// In DeepLinkHandler
const result = deepLinkSchemas.claim.safeParse(params);

5
doc/README.md
View File

@@ -6,7 +6,7 @@ This uses Pandoc and BasicTex (LaTeX) Installed through Homebrew.
### Set Up
```bash
```bash
brew install pandoc
brew install basictex
@@ -54,7 +54,7 @@ sudo tlmgr install sourceserifpro
The following guide was adapted to this project except that we install with Brew and have a few more packages.
Guide: https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x
Guide: <https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x>
### Usage
@@ -71,6 +71,7 @@ open usage-guide.pdf
```
Or use this one-liner
```bash
pandoc usage-guide.md -o usage-guide.pdf && open usage-guide.pdf
```

2
doc/architecture-decisions.md
View File

@@ -122,4 +122,4 @@ export default class HomeView extends Vue {
---
*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.*
*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.*

1
doc/asset-migration-plan.md
View File

@@ -103,6 +103,7 @@ scripts/
### Configuration Schema
The schema enforces:
- Source files must be in `resources/` directory
- Required fields for icon and splash sections
- Android adaptive icon support (foreground/background/monochrome)

10
doc/build-modernization-context.md
View File

@@ -3,11 +3,13 @@
**Author:** Matthew Raymer
## Motivation
- Eliminate manual hacks and post-build scripts for Electron builds
- Ensure maintainability, reproducibility, and security of build outputs
- Unify build, test, and deployment scripts for developer experience and CI/CD
## Key Technical Decisions
- **Vite is the single source of truth for build output**
- All Electron build output (main process, preload, renderer HTML/CSS/JS) is managed by `vite.config.electron.mts`
- **CSS injection for Electron is handled by a Vite plugin**
@@ -21,6 +23,7 @@
- Renderer assets: `dist-electron/www/` (HTML, CSS, JS)
## Security & Maintenance Checklist
- [x] All scripts and configs are committed and documented
- [x] No manual file hacks remain
- [x] All build output is deterministic and reproducible
@@ -28,24 +31,29 @@
- [x] Documentation (`BUILDING.md`) is up to date
## How to Build Electron
1. Run:
```bash
./scripts/build-electron.sh
```
2. Output will be in `dist-electron/`:
- `main.js`, `preload.js` in root
- `www/` contains all renderer assets
3. No manual post-processing is required
## Customization
- **Vite config:** All build output and asset handling is controlled in `vite.config.electron.mts`
- **CSS/HTML injection:** Use Vite plugins (see `electron-css-injection` in the config) for further customization
- **Build scripts:** All orchestration is in `scripts/` and documented in `BUILDING.md`
## For Future Developers
- Always use Vite plugins/config for build output changes
- Never manually edit built files or inject assets post-build
- Keep documentation and scripts in sync with the build process
---
This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference.
This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference.

21
doc/circular-dependency-analysis.md
View File

@@ -13,27 +13,31 @@ The codebase currently has **no active circular dependencies** that are causing
### 🔍 **Resolved Dependency Patterns**
#### 1. **Logger → PlatformServiceFactory → Logger** (RESOLVED)
- **Status**: ✅ **RESOLVED**
- **Previous Issue**: Logger imported `logToDb` from databaseUtil, which imported logger
- **Solution**: Logger now uses direct database access via PlatformServiceFactory
- **Implementation**: Self-contained `logToDatabase()` function in logger.ts
#### 2. **PlatformServiceMixin → databaseUtil → logger → PlatformServiceMixin** (RESOLVED)
- **Status**: ✅ **RESOLVED**
- **Previous Issue**: PlatformServiceMixin imported `memoryLogs` from databaseUtil
- **Solution**: Created self-contained `_memoryLogs` array in PlatformServiceMixin
- **Implementation**: Self-contained memory logs implementation
#### 3. **databaseUtil → logger → PlatformServiceFactory → databaseUtil** (RESOLVED)
- **Status**: ✅ **RESOLVED**
- **Previous Issue**: databaseUtil imported logger, which could create loops
- **Solution**: Logger is now self-contained and doesn't import from databaseUtil
#### 4. **Utility Files → databaseUtil → PlatformServiceMixin** (RESOLVED)
- **Status**: ✅ **RESOLVED**
- **Previous Issue**: `src/libs/util.ts` and `src/services/deepLinks.ts` imported from databaseUtil
- **Solution**: Replaced with self-contained implementations and PlatformServiceFactory usage
- **Implementation**:
- **Implementation**:
- Self-contained `parseJsonField()` and `mapQueryResultToValues()` functions
- Direct PlatformServiceFactory usage for database operations
- Console logging instead of databaseUtil logging functions
@@ -43,18 +47,21 @@ The codebase currently has **no active circular dependencies** that are causing
### ✅ **All Critical Dependencies Resolved**
#### PlatformServiceMixin Independence
- **Status**: ✅ **COMPLETE**
- **Achievement**: PlatformServiceMixin has no external dependencies on databaseUtil
- **Implementation**: Self-contained memory logs and utility functions
- **Impact**: Enables complete migration of databaseUtil functions to PlatformServiceMixin
#### Logger Independence
- **Status**: ✅ **COMPLETE**
- **Achievement**: Logger is completely self-contained
- **Implementation**: Direct database access via PlatformServiceFactory
- **Impact**: Eliminates all circular dependency risks
#### Utility Files Independence
- **Status**: ✅ **COMPLETE**
- **Achievement**: All utility files no longer depend on databaseUtil
- **Implementation**: Self-contained functions and direct platform service access
@@ -63,6 +70,7 @@ The codebase currently has **no active circular dependencies** that are causing
### 🎯 **Migration Readiness Status**
#### Files Ready for Migration (52 files)
1. **Components** (15 files):
- `PhotoDialog.vue`
- `FeedFilters.vue`
@@ -98,6 +106,7 @@ The codebase currently has **no active circular dependencies** that are causing
### 🟢 **Healthy Dependencies**
#### Logger Usage (80+ files)
- **Status**: ✅ **HEALTHY**
- **Pattern**: All files import logger from `@/utils/logger`
- **Impact**: No circular dependencies, logger is self-contained
@@ -106,21 +115,25 @@ The codebase currently has **no active circular dependencies** that are causing
## Resolution Strategy - COMPLETED
### ✅ **Phase 1: Complete PlatformServiceMixin Independence (COMPLETE)**
1. **Removed memoryLogs import** from PlatformServiceMixin ✅
2. **Created self-contained memoryLogs** implementation ✅
3. **Added missing utility methods** to PlatformServiceMixin ✅
### ✅ **Phase 2: Utility Files Migration (COMPLETE)**
1. **Migrated deepLinks.ts** - Replaced databaseUtil logging with console logging ✅
2. **Migrated util.ts** - Replaced databaseUtil functions with self-contained implementations ✅
3. **Updated all PlatformServiceFactory calls** to use async pattern ✅
### 🎯 **Phase 3: File-by-File Migration (READY TO START)**
1. **High-usage files first** (views, core components)
2. **Replace databaseUtil imports** with PlatformServiceMixin
3. **Update function calls** to use mixin methods
### 🎯 **Phase 4: Cleanup (FUTURE)**
1. **Remove unused databaseUtil functions**
2. **Update TypeScript interfaces**
3. **Remove databaseUtil imports** from all files
@@ -128,6 +141,7 @@ The codebase currently has **no active circular dependencies** that are causing
## Current Status Summary
### ✅ **Resolved Issues**
1. **Logger circular dependency** - Fixed with self-contained implementation
2. **PlatformServiceMixin circular dependency** - Fixed with self-contained memoryLogs
3. **Utility files circular dependency** - Fixed with self-contained implementations
@@ -135,6 +149,7 @@ The codebase currently has **no active circular dependencies** that are causing
5. **Runtime stability** - No circular dependency crashes
### 🎯 **Ready for Next Phase**
1. **52 files** ready for databaseUtil migration
2. **PlatformServiceMixin** fully independent and functional
3. **Clear migration path** - Well-defined targets and strategy
@@ -142,6 +157,7 @@ The codebase currently has **no active circular dependencies** that are causing
## Benefits of Current State
### ✅ **Achieved**
1. **No runtime circular dependencies** - Application runs without crashes
2. **Self-contained logger** - No more logger/databaseUtil loops
3. **PlatformServiceMixin ready** - All methods implemented and independent
@@ -149,6 +165,7 @@ The codebase currently has **no active circular dependencies** that are causing
5. **Clear migration path** - Well-defined targets and strategy
### 🎯 **Expected After Migration**
1. **Complete databaseUtil migration** - Single source of truth
2. **Eliminated circular dependencies** - Clean architecture
3. **Improved performance** - Caching and optimization
@@ -160,4 +177,4 @@ The codebase currently has **no active circular dependencies** that are causing
**Created**: 2025-07-05
**Status**: ✅ **COMPLETE - All Circular Dependencies Resolved**
**Last Updated**: 2025-01-06
**Note**: PlatformServiceMixin circular dependency completely resolved. Ready for Phase 2: File-by-File Migration
**Note**: PlatformServiceMixin circular dependency completely resolved. Ready for Phase 2: File-by-File Migration

16
doc/component-communication-guide.md
View File

@@ -93,6 +93,7 @@ export default class FormComponent extends Vue {
When generating component templates, follow these patterns:
#### Function Props Template
```vue
<template>
<div class="component-name">
@@ -124,6 +125,7 @@ export default class ComponentName extends Vue {
```
#### $emit Template (for DOM events)
```vue
<template>
<div class="component-name">
@@ -155,12 +157,14 @@ export default class ComponentName extends Vue {
### Code Generation Rules
#### 1. Function Props for Business Logic
- **Data operations**: Save, delete, update, validate
- **Navigation**: Route changes, modal opening/closing
- **State management**: Store actions, state updates
- **API calls**: Data fetching, form submissions
#### 2. $emit for User Interactions
- **Click events**: Button clicks, link navigation
- **Form events**: Input changes, form submissions
- **Lifecycle events**: Component mounting, unmounting
@@ -169,6 +173,7 @@ export default class ComponentName extends Vue {
#### 3. Naming Conventions
**Function Props:**
```typescript
// Action-oriented names
onSave: (data: SaveData) => Promise<void>
@@ -179,6 +184,7 @@ onNavigate: (route: string) => void
```
**$emit Events:**
```typescript
// Event-oriented names
@click: (event: MouseEvent) => void
@@ -191,6 +197,7 @@ onNavigate: (route: string) => void
### TypeScript Integration
#### Function Prop Types
```typescript
// Define reusable function types
interface SaveHandler {
@@ -207,6 +214,7 @@ interface ValidationHandler {
```
#### Event Types
```typescript
// Define event payload types
interface ClickEvent {
@@ -226,6 +234,7 @@ handleClick(): ClickEvent {
## Testing Guidelines
### Function Props Testing
```typescript
// Easy to mock and test
const mockOnSave = jest.fn();
@@ -240,6 +249,7 @@ expect(mockOnSave).toHaveBeenCalledWith(expectedData);
```
### $emit Testing
```typescript
// Requires event simulation
const wrapper = mount(MyComponent);
@@ -260,6 +270,7 @@ expect(wrapper.emitted('click')).toBeTruthy();
### Example Migration
**Before ($emit):**
```typescript
@Emit("save")
handleSave() {
@@ -268,6 +279,7 @@ handleSave() {
```
**After (Function Props):**
```typescript
@Prop({ required: true }) onSave!: (data: FormData) => void;
@@ -288,6 +300,7 @@ handleSave() {
## Code Generation Templates
### Component Generator Input
```typescript
interface ComponentSpec {
name: string;
@@ -306,9 +319,10 @@ interface ComponentSpec {
```
### Generated Output
```typescript
// Generator should automatically choose function props vs $emit
// based on the nature of the interaction (business logic vs DOM event)
```
This guide ensures consistent, maintainable component communication patterns across the application.
This guide ensures consistent, maintainable component communication patterns across the application.

16
doc/cors-disabled-for-universal-images.md
View File

@@ -7,10 +7,12 @@ CORS headers have been **disabled** to support Time Safari's core mission: enabl
## What Changed
### ❌ Removed CORS Headers
- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Embedder-Policy: require-corp`
### ✅ Results
- Images from **any domain** now work in development and production
- No proxy configuration needed
- No whitelist of supported image hosts
@@ -19,11 +21,13 @@ CORS headers have been **disabled** to support Time Safari's core mission: enabl
## Technical Tradeoffs
### 🔻 Lost: SharedArrayBuffer Performance
- **Before**: Fast SQLite operations via SharedArrayBuffer
- **After**: Slightly slower IndexedDB fallback mode
- **Impact**: Minimal for typical usage - absurd-sql automatically falls back
### 🔺 Gained: Universal Image Support
- **Before**: Only specific domains worked (TimeSafari, Flickr, Imgur, etc.)
- **After**: Any image URL works immediately
- **Impact**: Massive improvement for user experience
@@ -31,6 +35,7 @@ CORS headers have been **disabled** to support Time Safari's core mission: enabl
## Architecture Impact
### Database Operations
```typescript
// absurd-sql automatically detects SharedArrayBuffer availability
if (typeof SharedArrayBuffer === "undefined") {
@@ -43,6 +48,7 @@ if (typeof SharedArrayBuffer === "undefined") {
```
### Image Loading
```typescript
// All images load directly now
export function transformImageUrlForCors(imageUrl: string): string {
@@ -53,11 +59,13 @@ export function transformImageUrlForCors(imageUrl: string): string {
## Why This Was The Right Choice
### Time Safari's Use Case
- **Community platform** where users share content from anywhere
- **User-generated content** includes images from arbitrary websites
- **Flexibility** is more important than marginal performance gains
### Alternative Would Require
- Pre-configuring proxies for every possible image hosting service
- Constantly updating proxy list as users find new sources
- Poor user experience when images fail to load
@@ -66,11 +74,13 @@ export function transformImageUrlForCors(imageUrl: string): string {
## Performance Comparison
### Database Operations
- **SharedArrayBuffer**: ~2x faster for large operations
- **IndexedDB**: Still very fast for typical Time Safari usage
- **Real Impact**: Negligible for typical user operations
### Image Loading
- **With CORS**: Many images failed to load in development
- **Without CORS**: All images load immediately
- **Real Impact**: Massive improvement in user experience
@@ -87,11 +97,13 @@ export function transformImageUrlForCors(imageUrl: string): string {
## Migration Notes
### For Developers
- No code changes needed
- `transformImageUrlForCors()` still exists but returns original URL
- All existing image references work without modification
### For Users
- Images from any website now work immediately
- No more "image failed to load" issues in development
- Consistent behavior between development and production
@@ -99,12 +111,14 @@ export function transformImageUrlForCors(imageUrl: string): string {
## Future Considerations
### If Performance Becomes Critical
1. **Selective CORS**: Enable only for specific operations
2. **Service Worker**: Handle image proxying at service worker level
3. **Build-time Processing**: Pre-process images during build
4. **User Education**: Guide users toward optimized image hosting
### Monitoring
- Track database operation performance
- Monitor for any user-reported slowness
- Consider re-enabling SharedArrayBuffer if usage patterns change
@@ -113,4 +127,4 @@ export function transformImageUrlForCors(imageUrl: string): string {
This change prioritizes **user experience** and **community functionality** over marginal performance gains. The database still works efficiently via IndexedDB, while images now work universally without configuration.
For a community platform like Time Safari, the ability to share images from any domain is fundamental to the user experience and mission.
For a community platform like Time Safari, the ability to share images from any domain is fundamental to the user experience and mission.

28
doc/cors-image-loading-solution.md
View File

@@ -7,6 +7,7 @@ This document describes the implementation of a comprehensive image loading solu
## Problem Statement
When using SharedArrayBuffer (required for absurd-sql), browsers enforce a cross-origin isolated environment with these headers:
- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Embedder-Policy: require-corp`
@@ -19,6 +20,7 @@ This isolation prevents loading external resources (including images) unless the
The solution uses a multi-tier approach to handle images from various sources:
#### Tier 1: Specific Domain Proxies (Development Only)
- **TimeSafari Images**: `/image-proxy/` → `https://image.timesafari.app/`
- **Flickr Images**: `/flickr-proxy/` → `https://live.staticflickr.com/`
- **Imgur Images**: `/imgur-proxy/` → `https://i.imgur.com/`
@@ -26,14 +28,17 @@ The solution uses a multi-tier approach to handle images from various sources:
- **Unsplash**: `/unsplash-proxy/` → `https://images.unsplash.com/`
#### Tier 2: Universal CORS Proxy (Development Only)
- **Any External Domain**: Uses `https://api.allorigins.win/raw?url=` for arbitrary domains
#### Tier 3: Direct Loading (Production)
- **Production Mode**: All images load directly without proxying
### 2. Smart URL Transformation
The `transformImageUrlForCors` function automatically:
- Detects the image source domain
- Routes through appropriate proxy in development
- Preserves original URLs in production
@@ -44,6 +49,7 @@ The `transformImageUrlForCors` function automatically:
### Configuration Files
#### `vite.config.common.mts`
```typescript
server: {
headers: {
@@ -63,6 +69,7 @@ server: {
```
#### `src/libs/util.ts`
```typescript
export function transformImageUrlForCors(imageUrl: string): string {
// Development mode: Transform URLs to use proxies
@@ -93,21 +100,25 @@ const imageUrl = transformImageUrlForCors(originalImageUrl);
## Benefits
### ✅ SharedArrayBuffer Support
- Maintains cross-origin isolation required for SharedArrayBuffer
- Enables fast SQLite database operations via absurd-sql
- Provides better performance than IndexedDB fallback
### ✅ Universal Image Support
- Handles images from any domain
- No need to pre-configure every possible image source
- Graceful fallback for unknown domains
### ✅ Development/Production Flexibility
- Proxy system only active in development
- Production uses direct URLs for maximum performance
- No proxy server required in production
### ✅ Automatic Detection
- Smart URL transformation based on domain patterns
- Preserves relative URLs and data URLs
- Handles edge cases gracefully
@@ -115,6 +126,7 @@ const imageUrl = transformImageUrlForCors(originalImageUrl);
## Testing
### Automated Testing
Run the test suite to verify URL transformation:
```typescript
@@ -125,6 +137,7 @@ testCorsImageTransformation();
```
### Visual Testing
Create test image elements to verify loading:
```typescript
@@ -135,6 +148,7 @@ createTestImageElements();
```
### Manual Testing
1. Start development server: `npm run dev`
2. Open browser console to see transformation logs
3. Check Network tab for proxy requests
@@ -143,16 +157,19 @@ createTestImageElements();
## Security Considerations
### Development Environment
- CORS proxies are only used in development
- External proxy services (allorigins.win) are used for testing
- No sensitive data is exposed through proxies
### Production Environment
- All images load directly without proxying
- No dependency on external proxy services
- Original security model maintained
### Privacy
- Image URLs are not logged or stored by proxy services
- Proxy requests are only made during development
- No tracking or analytics in proxy chain
@@ -160,11 +177,13 @@ createTestImageElements();
## Performance Impact
### Development
- Slight latency from proxy requests
- Additional network hops for external domains
- More verbose logging for debugging
### Production
- No performance impact
- Direct image loading as before
- No proxy overhead
@@ -174,17 +193,20 @@ createTestImageElements();
### Common Issues
#### Images Not Loading in Development
1. Check console for proxy errors
2. Verify CORS headers are set
3. Test with different image URLs
4. Check network connectivity to proxy services
#### SharedArrayBuffer Not Available
1. Verify CORS headers are set in server configuration
2. Check that site is served over HTTPS (or localhost)
3. Ensure browser supports SharedArrayBuffer
#### Proxy Service Unavailable
1. Check if allorigins.win is accessible
2. Consider using alternative CORS proxy services
3. Temporarily disable CORS headers for testing
@@ -207,12 +229,14 @@ testCorsImageTransformation();
## Migration Guide
### From Previous Implementation
1. CORS headers are now required for SharedArrayBuffer
2. Image URLs automatically transformed in development
3. No changes needed to existing image loading code
4. Test thoroughly in both development and production
### Adding New Image Sources
1. Add specific proxy for frequently used domains
2. Update `transformImageUrlForCors` function
3. Add CORS headers to proxy configuration
@@ -221,6 +245,7 @@ testCorsImageTransformation();
## Future Enhancements
### Possible Improvements
1. **Local Proxy Server**: Run dedicated proxy server for development
2. **Caching**: Cache proxy responses for better performance
3. **Fallback Chain**: Multiple proxy services for reliability
@@ -228,6 +253,7 @@ testCorsImageTransformation();
5. **Analytics**: Track image loading success/failure rates
### Alternative Approaches
1. **Service Worker**: Intercept image requests at service worker level
2. **Build-time Processing**: Pre-process images during build
3. **CDN Integration**: Use CDN with proper CORS headers
@@ -237,4 +263,4 @@ testCorsImageTransformation();
This solution provides a robust, scalable approach to image loading in a cross-origin isolated environment while maintaining the benefits of SharedArrayBuffer support. The multi-tier proxy system ensures compatibility with any image source while optimizing for performance and security.
For questions or issues, refer to the troubleshooting section or consult the development team.
For questions or issues, refer to the troubleshooting section or consult the development team.

1
doc/database-migration-guide.md
View File

@@ -294,6 +294,7 @@ const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDi
```
This provides:
- **Caching**: Automatic caching for performance
- **Error Handling**: Consistent error handling
- **Type Safety**: Enhanced TypeScript integration

5
doc/debug-hook-guide.md
View File

@@ -120,6 +120,7 @@ git commit -m "test" # Should be blocked
## ⚙️ Configuration
Edit `.git/hooks/debug-checker.config` to customize:
- **Protected branches**: Add/remove branches as needed
- **Debug patterns**: Customize what gets detected
- **Skip patterns**: Adjust file filtering rules
@@ -127,14 +128,17 @@ Edit `.git/hooks/debug-checker.config` to customize:
## 🚨 Emergency Bypass
If you absolutely need to commit debug code to a protected branch:
```bash
git commit --no-verify -m "emergency: debug code needed"
```
⚠️ **Warning**: This bypasses all pre-commit hooks. Use sparingly.
## 🔄 Updates
When the hook is updated in the main repository:
```bash
./scripts/install-debug-hook.sh
```
@@ -170,6 +174,7 @@ A test script is available at `scripts/test-debug-hook.sh` to verify the hook wo
## 🎯 Team Workflow
**Recommended setup:**
1. **Repository setup**: Include hook files in `.githooks/` directory
2. **Team onboarding**: Run installation script in each repo
3. **Updates**: Re-run installation script when hooks are updated

8
doc/electron-cleanup-summary.md
View File

@@ -7,18 +7,22 @@ This document summarizes the comprehensive cleanup and improvements made to the
## Key Issues Resolved
### 1. Platform Detection Problems
- **Before**: `PlatformServiceFactory` only supported "capacitor" and "web" platforms
- **After**: Added proper "electron" platform support with dedicated `ElectronPlatformService`
### 2. Build Configuration Confusion
- **Before**: Electron builds used `VITE_PLATFORM=capacitor`, causing confusion
- **After**: Electron builds now properly use `VITE_PLATFORM=electron`
### 3. Missing Platform Service Methods
- **Before**: Platform services lacked proper `isElectron()`, `isCapacitor()`, `isWeb()` methods
- **After**: All platform services implement complete interface with proper detection
### 4. Inconsistent Build Scripts
- **Before**: Mixed platform settings in build scripts
- **After**: Clean, consistent electron-specific build process
@@ -215,11 +219,13 @@ if (capabilities.hasFileDownload) {
## File Structure Changes
### New Files
- `vite.config.electron.mts` - Electron-specific Vite configuration
- `src/main.electron.ts` - Electron main entry point
- `doc/electron-cleanup-summary.md` - This documentation
### Modified Files
- `src/services/PlatformServiceFactory.ts` - Added electron platform support
- `src/services/PlatformService.ts` - Added platform detection methods
- `src/services/platforms/CapacitorPlatformService.ts` - Added missing interface methods
@@ -301,4 +307,4 @@ For developers working with the previous implementation:
- [ ] Implement desktop-specific UI components
- [ ] Add Electron auto-updater integration
- [ ] Create platform-specific testing utilities
- [ ] Add desktop notification system integration
- [ ] Add desktop notification system integration

27
doc/electron-console-cleanup.md
View File

@@ -7,18 +7,22 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Issues Addressed
### 1. Excessive Database Logging (Major Issue - 90% Reduction)
**Problem:** Every database operation was logging detailed parameter information, creating hundreds of lines of console output.
**Solution:** Modified `src/services/platforms/CapacitorPlatformService.ts`:
- Changed `logger.warn` to `logger.debug` for routine SQL operations
- Reduced migration logging verbosity
- Reduced migration logging verbosity
- Made database integrity checks use debug-level logging
- Kept error and completion messages at appropriate log levels
### 2. Enhanced Logger Configuration
**Problem:** No platform-specific logging controls, causing noise in Electron.
**Solution:** Updated `src/utils/logger.ts`:
- Added platform detection for Electron vs Web
- Suppressed debug and verbose logs for Electron
- Filtered out routine database operations from database logging
@@ -26,28 +30,35 @@ This document summarizes the comprehensive changes made to reduce excessive cons
- Added intelligent filtering for CapacitorPlatformService messages
### 3. API Configuration Issues (Major Fix)
**Problem:** Electron was trying to use local development endpoints (localhost:3000) from saved user settings, which don't exist in desktop environment, causing:
- 400 status errors from missing local development servers
- JSON parsing errors (HTML error pages instead of JSON responses)
**Solution:**
**Solution:**
- Updated `src/constants/app.ts` to provide Electron-specific API endpoints
- **Critical Fix:** Modified `src/db/databaseUtil.ts` in `retrieveSettingsForActiveAccount()` to force Electron to use production API endpoints regardless of saved user settings
- This ensures Electron never uses localhost development servers that users might have saved
### 4. SharedArrayBuffer Logging Noise
**Problem:** Web-specific SharedArrayBuffer detection was running in Electron, creating unnecessary debug output.
**Solution:** Modified `src/main.web.ts`:
- Made SharedArrayBuffer logging conditional on web platform only
- Converted console.log statements to logger.debug
- Only show in development mode for web platform
- Reduced platform detection noise
### 5. Missing Source Maps Warnings
**Problem:** Electron DevTools was complaining about missing source maps for external dependencies.
**Solution:** Updated `vite.config.electron.mts`:
- Disabled source maps for Electron builds (`sourcemap: false`)
- Added build configuration to suppress external dependency warnings
- Prevents DevTools from looking for non-existent source map files
@@ -87,14 +98,16 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Impact
### Before Cleanup:
### Before Cleanup
- 500+ lines of console output per minute
- Detailed SQL parameter logging for every operation
- API connection errors every few seconds (400 status, JSON parsing errors)
- SharedArrayBuffer warnings on every startup
- DevTools source map warnings
### After Cleanup:
### After Cleanup
- **~95% reduction** in console output
- Only errors and important status messages visible
- **No API connection errors** - Electron uses proper production endpoints
@@ -106,6 +119,7 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Technical Details
### API Configuration Fix
The most critical fix was in `src/db/databaseUtil.ts` where we added:
```typescript
@@ -122,6 +136,7 @@ if (process.env.VITE_PLATFORM === "electron") {
This ensures that even if users have localhost development endpoints saved in their settings, Electron will override them with production endpoints.
### Logger Enhancement
Enhanced the logger with platform-specific behavior:
```typescript
@@ -135,6 +150,7 @@ if (!isElectron || !message.includes("[CapacitorPlatformService]")) {
## Testing
The changes were tested with:
- `npm run lint-fix` - 0 errors, warnings only (pre-existing)
- Electron development environment
- Web platform (unchanged functionality)
@@ -150,6 +166,7 @@ The changes were tested with:
## Backward Compatibility
All changes maintain backward compatibility:
- Web platform logging unchanged
- Capacitor platform logging unchanged
- Error handling preserved
@@ -185,4 +202,4 @@ Tests: lint passes, Web/Capacitor functionality preserved
1. **Test the fixes** - Run `npm run electron:dev` to verify console noise is eliminated
2. **Monitor for remaining issues** - Check for any other console noise sources
3. **Performance monitoring** - Verify the reduced logging doesn't impact functionality
4. **Documentation updates** - Update any development guides that reference the old logging behavior
4. **Documentation updates** - Update any development guides that reference the old logging behavior

19
doc/error-diagnostics-log.md
View File

@@ -5,9 +5,10 @@ This file tracks console errors observed during development for future investiga
## 2025-07-07 08:56 UTC - ProjectsView.vue Migration Session
### Migration Context
- **Current Work**: Completed ProjectsView.vue Triple Migration Pattern
- **Migration Status**: 21 complete, 4 appropriately incomplete components
- **Recent Changes**:
- **Recent Changes**:
- ProjectsView.vue: databaseUtil → PlatformServiceMixin
- Added notification constants and literal string extraction
- Template logic streamlining with computed properties
@@ -15,42 +16,50 @@ This file tracks console errors observed during development for future investiga
### Observed Errors
#### 1. HomeView.vue API Rate Limit Errors
```
GET https://api.endorser.ch/api/report/rateLimits 400 (Bad Request)
Source: endorserServer.ts:1494, HomeView.vue:593, HomeView.vue:742
```
**Analysis**:
**Analysis**:
- API server returning 400 for rate limit checks
- Occurs during identity initialization and registration status checks
- **Migration Impact**: None - HomeView.vue was migrated and tested earlier
- **Likely Cause**: Server-side authentication or API configuration issue
**Action Items**:
- [ ] Check endorser.ch API documentation for rate limit endpoint changes
- [ ] Verify authentication headers being sent correctly
- [ ] Consider fallback handling for rate limit API failures
#### 2. ProjectViewView.vue Project Not Found Error
```
GET https://api.endorser.ch/api/claim/byHandle/...01JY2Q5D90E8P267ABB963S71D 404 (Not Found)
Source: ProjectViewView.vue:830 loadProject() method
```
**Analysis**:
- Attempting to load project ID: `01JY2Q5D90E8P267ABB963S71D`
- **Migration Impact**: None - error handling working correctly
- **Likely Cause**: User navigated to non-existent project or stale link
**Action Items**:
- [ ] Consider adding better user messaging for missing projects
- [ ] Investigate if project IDs are being generated/stored correctly
- [ ] Add breadcrumb or "return to projects" option on 404s
#### 3. Axios Request Stack Traces
Multiple stack traces showing Vue router navigation and component mounting cycles.
**Analysis**:
- Normal Vue.js lifecycle and routing behavior
- No obvious memory leaks or infinite loops
- **Migration Impact**: None - expected framework behavior
@@ -58,26 +67,30 @@ Multiple stack traces showing Vue router navigation and component mounting cycle
### System Health Indicators
#### ✅ Working Correctly
- Database migrations: `Migration process complete! Summary: 0 applied, 2 skipped`
- Platform service factory initialization: `Creating singleton instance for platform: development`
- SQL worker loading: `Worker loaded, ready to receive messages`
- Database connection: `Opened!`
#### 🔄 For Investigation
- API authentication/authorization with endorser.ch
- Project ID validation and error handling
- Rate limiting strategy
### Migration Validation
- **ProjectsView.vue**: Appropriately incomplete (3 helpers + 1 complex modal)
- **Error Handling**: Migrated components showing proper error handling
- **No Migration-Related Errors**: All errors appear to be infrastructure/data issues
### Next Steps
1. Continue migration slog with next component
2. Monitor these same error patterns in future sessions
3. Address API/server issues in separate debugging session
---
*Log Entry by: Migration Assistant*
*Session: ProjectsView.vue Triple Migration Pattern*
*Session: ProjectsView.vue Triple Migration Pattern*

23
doc/image-hosting-guide.md
View File

@@ -25,6 +25,7 @@
## Why This Happens
In development mode, we enable SharedArrayBuffer for fast SQLite operations, which requires:
- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Embedder-Policy: require-corp`
@@ -35,6 +36,7 @@ These headers create a **cross-origin isolated environment** that blocks resourc
### 1. Use Supported Image Hosting Services
**Recommended services that work well:**
- **Imgur**: Free, no registration required, direct links
- **GitHub**: If you have images in repositories
- **Unsplash**: For stock photos
@@ -45,6 +47,7 @@ These headers create a **cross-origin isolated environment** that blocks resourc
If you frequently use images from a specific domain, add a proxy:
#### Step 1: Add Proxy to `vite.config.common.mts`
```typescript
'/yourservice-proxy': {
target: 'https://yourservice.com',
@@ -63,6 +66,7 @@ If you frequently use images from a specific domain, add a proxy:
```
#### Step 2: Update Transform Function in `src/libs/util.ts`
```typescript
// Transform YourService URLs to use proxy
if (imageUrl.startsWith("https://yourservice.com/")) {
@@ -74,6 +78,7 @@ if (imageUrl.startsWith("https://yourservice.com/")) {
### 3. Use Alternative Image Sources
For frequently failing domains, consider:
- Upload images to Imgur or GitHub
- Use a CDN with proper CORS headers
- Host images on your own domain with CORS enabled
@@ -81,11 +86,13 @@ For frequently failing domains, consider:
## Development vs Production
### Development Mode
- Images from supported services work through proxies
- Unsupported images may fail to load
- Console warnings show which images have issues
### Production Mode
- All images load directly without proxies
- No CORS restrictions in production
- Better performance without proxy overhead
@@ -93,6 +100,7 @@ For frequently failing domains, consider:
## Testing Image Sources
### Check if an Image Source Works
```bash
# Test in browser console:
fetch('https://example.com/image.jpg', { mode: 'cors' })
@@ -101,6 +109,7 @@ fetch('https://example.com/image.jpg', { mode: 'cors' })
```
### Visual Testing
```typescript
import { createTestImageElements } from './libs/test-cors-images';
createTestImageElements(); // Creates visual test panel
@@ -109,30 +118,36 @@ createTestImageElements(); // Creates visual test panel
## Common Error Messages
### `ERR_BLOCKED_BY_RESPONSE.NotSameOriginAfterDefaultedToSameOriginByCoep`
**Cause**: Image source doesn't send required CORS headers
**Solution**: Use a supported image hosting service or add a proxy
### `ERR_NETWORK` or `ERR_INTERNET_DISCONNECTED`
**Cause**: Proxy service is unavailable
**Solution**: Check internet connection or use alternative image source
### Images Load in Production but Not Development
**Cause**: Normal behavior - development has stricter CORS requirements
**Solution**: Use supported image sources for development testing
## Best Practices
### For New Projects
1. Use supported image hosting services from the start
2. Upload user images to Imgur or similar service
3. Host critical images on your own domain with CORS enabled
### For Existing Projects
1. Identify frequently used image domains in console warnings
2. Add proxies for the most common domains
3. Gradually migrate to supported image hosting services
### For User-Generated Content
1. Provide upload functionality to supported services
2. Validate image URLs against supported domains
3. Show helpful error messages for unsupported sources
@@ -140,17 +155,20 @@ createTestImageElements(); // Creates visual test panel
## Troubleshooting
### Image Not Loading?
1. Check browser console for error messages
2. Verify the domain is in the supported list
3. Test if the image loads in production mode
4. Consider adding a proxy for that domain
### Proxy Not Working?
1. Check if the target service allows proxying
2. Verify CORS headers are being set correctly
3. Test with a simpler image URL from the same domain
### Performance Issues?
1. Proxies add latency in development only
2. Production uses direct image loading
3. Consider using a local image cache for development
@@ -158,6 +176,7 @@ createTestImageElements(); // Creates visual test panel
## Quick Fixes
### For Immediate Issues
```typescript
// Temporary fallback: disable CORS headers for testing
// In vite.config.common.mts, comment out:
@@ -166,9 +185,11 @@ createTestImageElements(); // Creates visual test panel
// 'Cross-Origin-Embedder-Policy': 'require-corp'
// },
```
**Note**: This disables SharedArrayBuffer performance benefits.
### For Long-term Solution
- Use supported image hosting services
- Add proxies for frequently used domains
- Migrate critical images to your own CORS-enabled CDN
@@ -177,4 +198,4 @@ createTestImageElements(); // Creates visual test panel
The cross-origin isolated environment is necessary for SharedArrayBuffer performance but requires careful image source management. Use the supported services, add proxies for common domains, and accept that some external images may not work in development mode.
This is a development-only limitation - production deployments work with any image source.
This is a development-only limitation - production deployments work with any image source.

2
doc/logging-configuration.md
View File

@@ -101,6 +101,7 @@ Database logging continues to work regardless of console log level settings. All
### No Logs Appearing
Check your `VITE_LOG_LEVEL` setting:
```bash
echo $VITE_LOG_LEVEL
```
@@ -108,6 +109,7 @@ echo $VITE_LOG_LEVEL
### Too Many Logs
Reduce verbosity by setting a lower log level:
```bash
VITE_LOG_LEVEL=warn
```

23
doc/migration-fence-definition.md
View File

@@ -9,6 +9,7 @@ This document defines the **migration fence** - the boundary between the legacy
## 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
@@ -17,12 +18,14 @@ This document defines the **migration fence** - the boundary between the legacy
- **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
@@ -45,6 +48,7 @@ export const PlatformServiceMixin = {
```
**Fence Rule**: All database operations must use:
- `this.$db()` for read operations
- `this.$exec()` for write operations
- `this.$settings()` for settings access
@@ -64,6 +68,7 @@ export class PlatformServiceFactory {
```
**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
@@ -71,6 +76,7 @@ export class PlatformServiceFactory {
### 3. Data Access Patterns
#### ✅ Allowed (Inside Fence)
```typescript
// Use PlatformServiceMixin for all database operations
const contacts = await this.$contacts();
@@ -79,6 +85,7 @@ const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDi
```
#### ❌ Forbidden (Outside Fence)
```typescript
// Direct Dexie access (legacy pattern)
const contacts = await db.contacts.where('did').equals(accountDid).toArray();
@@ -98,6 +105,7 @@ export async function compareDatabases(): Promise<DataComparison> {
```
**Fence Rule**: Migration tools are the exclusive interface between:
- Legacy Dexie database
- New SQLite database
- Data comparison and transfer operations
@@ -107,11 +115,13 @@ export async function compareDatabases(): Promise<DataComparison> {
### 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
@@ -119,11 +129,13 @@ export async function compareDatabases(): Promise<DataComparison> {
### 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
@@ -131,6 +143,7 @@ export async function compareDatabases(): Promise<DataComparison> {
### 3. Testing Requirements
#### Migration Testing
```typescript
// Required test pattern for migration
describe('Database Migration', () => {
@@ -144,6 +157,7 @@ describe('Database Migration', () => {
```
#### Application Testing
```typescript
// Required test pattern for application features
describe('Feature with Database', () => {
@@ -159,6 +173,7 @@ describe('Feature with Database', () => {
### 1. Static Analysis
#### ESLint Rules
```json
{
"rules": {
@@ -178,6 +193,7 @@ describe('Feature with Database', () => {
```
#### TypeScript Rules
```json
{
"compilerOptions": {
@@ -190,6 +206,7 @@ describe('Feature with Database', () => {
### 2. Runtime Checks
#### Development Mode Validation
```typescript
// Development-only fence validation
if (import.meta.env.DEV) {
@@ -198,6 +215,7 @@ if (import.meta.env.DEV) {
```
#### Production Safety
```typescript
// Production fence enforcement
if (import.meta.env.PROD) {
@@ -209,6 +227,7 @@ if (import.meta.env.PROD) {
## Migration Status Checklist
### ✅ Completed
- [x] PlatformServiceMixin implementation
- [x] SQLite database service
- [x] Migration tools
@@ -217,11 +236,13 @@ if (import.meta.env.PROD) {
- [x] ActiveDid migration
### 🔄 In Progress
- [ ] Contact migration
- [ ] DatabaseUtil to PlatformServiceMixin migration
- [ ] File-by-file migration
### ❌ Not Started
- [ ] Legacy Dexie removal
- [ ] Final cleanup and validation
@@ -240,4 +261,4 @@ if (import.meta.env.PROD) {
**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
**Note**: Migration fence now implemented through PlatformServiceMixin instead of USE_DEXIE_DB constant

71
doc/migration-progress-tracker.md
View File

@@ -3,6 +3,7 @@
## Per-File Migration Workflow (MANDATORY)
For each file migrated:
1. **First**, migrate to PlatformServiceMixin (replace all databaseUtil usage, etc.).
2. **Immediately after**, standardize notify helper usage (property + created() pattern) and fix any related linter/type errors.
@@ -25,22 +26,26 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
## ✅ **DAY 1: PlatformServiceMixin Completion (COMPLETE)**
### **Phase 1: Remove Circular Dependency (COMPLETE)**
**Status**: ✅ **COMPLETE**
**Issue**: PlatformServiceMixin imports `memoryLogs` from databaseUtil
**Solution**: Create self-contained memoryLogs implementation
#### **Tasks**:
#### **Tasks**
- [x] **Step 1.1**: Remove `memoryLogs` import from PlatformServiceMixin.ts ✅
- [x] **Step 1.2**: Add self-contained `_memoryLogs` array to PlatformServiceMixin ✅
- [x] **Step 1.3**: Add `$appendToMemoryLogs()` method to PlatformServiceMixin ✅
- [x] **Step 1.4**: Update logger.ts to use self-contained memoryLogs ✅
- [x] **Step 1.5**: Test memoryLogs functionality ✅
#### **Files Modified**:
#### **Files Modified**
- `src/utils/PlatformServiceMixin.ts` ✅
- `src/utils/logger.ts` ✅
#### **Validation**:
#### **Validation**
- [x] No circular dependency errors ✅
- [x] memoryLogs functionality works correctly ✅
- [x] Linting passes ✅
@@ -48,20 +53,24 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
---
### **Phase 2: Add Missing Utility Functions (COMPLETE)**
**Status**: ✅ **COMPLETE**
**Missing Functions**: `generateInsertStatement`, `generateUpdateStatement`
#### **Tasks**:
#### **Tasks**
- [x] **Step 2.1**: Add `_generateInsertStatement()` private method to PlatformServiceMixin ✅
- [x] **Step 2.2**: Add `_generateUpdateStatement()` private method to PlatformServiceMixin ✅
- [x] **Step 2.3**: Add `$generateInsertStatement()` public wrapper method ✅
- [x] **Step 2.4**: Add `$generateUpdateStatement()` public wrapper method ✅
- [x] **Step 2.5**: Test both utility functions ✅
#### **Files Modified**:
#### **Files Modified**
- `src/utils/PlatformServiceMixin.ts` ✅
#### **Validation**:
#### **Validation**
- [x] Both functions generate correct SQL ✅
- [x] Parameter handling works correctly ✅
- [x] Type safety maintained ✅
@@ -69,18 +78,22 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
---
### **Phase 3: Update Type Definitions (COMPLETE)**
**Status**: ✅ **COMPLETE**
**Goal**: Add new methods to TypeScript interfaces
#### **Tasks**:
#### **Tasks**
- [x] **Step 3.1**: Add new methods to `IPlatformServiceMixin` interface ✅
- [x] **Step 3.2**: Add new methods to `ComponentCustomProperties` interface ✅
- [x] **Step 3.3**: Verify TypeScript compilation ✅
#### **Files Modified**:
#### **Files Modified**
- `src/utils/PlatformServiceMixin.ts` (interface definitions) ✅
#### **Validation**:
#### **Validation**
- [x] TypeScript compilation passes ✅
- [x] All new methods properly typed ✅
- [x] No type errors in existing code ✅
@@ -88,17 +101,20 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
---
### **Phase 4: Testing & Validation (COMPLETE)**
**Status**: ✅ **COMPLETE**
**Goal**: Ensure PlatformServiceMixin is fully functional
#### **Tasks**:
#### **Tasks**
- [x] **Step 4.1**: Create test component to verify all methods ✅
- [x] **Step 4.2**: Run comprehensive linting ✅
- [x] **Step 4.3**: Run TypeScript type checking ✅
- [x] **Step 4.4**: Test caching functionality ✅
- [x] **Step 4.5**: Test database operations ✅
#### **Validation**:
#### **Validation**
- [x] All tests pass ✅
- [x] No linting errors ✅
- [x] No TypeScript errors ✅
@@ -108,10 +124,12 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
---
### **Phase 5: Utility Files Migration (COMPLETE)**
**Status**: ✅ **COMPLETE**
**Goal**: Remove all remaining databaseUtil imports from utility files
#### **Tasks**:
#### **Tasks**
- [x] **Step 5.1**: Migrate `src/services/deepLinks.ts` ✅
- Replaced `logConsoleAndDb` with `console.error`
- Removed databaseUtil import
@@ -121,7 +139,8 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
- Updated all async calls to use proper async pattern
- [x] **Step 5.3**: Verify no remaining databaseUtil imports ✅
#### **Validation**:
#### **Validation**
- [x] No databaseUtil imports in any TypeScript files ✅
- [x] No databaseUtil imports in any Vue files ✅
- [x] All functions work correctly ✅
@@ -131,13 +150,16 @@ This document tracks the progress of the 2-day sprint to complete PlatformServic
## 🎯 **DAY 2: Migrate All 52 Files (READY TO START)**
### **Migration Strategy**
**Priority Order**:
1. **Views** (25 files) - User-facing components
2. **Components** (15 files) - Reusable UI components
3. **Services** (8 files) - Business logic
4. **Utils** (4 files) - Utility functions
### **Migration Pattern for Each File**
```typescript
// 1. Add PlatformServiceMixin
import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
@@ -155,6 +177,7 @@ export default class ComponentName extends Vue {
```
### **Common Replacements**
- `generateInsertStatement` → `this.$generateInsertStatement`
- `generateUpdateStatement` → `this.$generateUpdateStatement`
- `parseJsonField` → `this._parseJsonField`
@@ -168,6 +191,7 @@ export default class ComponentName extends Vue {
## 📋 **File Migration Checklist**
### **Views (25 files) - Priority 1**
**Progress**: 6/25 (24%)
- [ ] QuickActionBvcEndView.vue
@@ -209,6 +233,7 @@ export default class ComponentName extends Vue {
- [ ] UserProfileView.vue
### **Components (15 files) - Priority 2**
**Progress**: 9/15 (60%)
- [x] UserNameDialog.vue ✅ **MIGRATED**
@@ -233,6 +258,7 @@ export default class ComponentName extends Vue {
- [x] IconRenderer.vue ✅ MIGRATED & HUMAN TESTED 2024-12-19 (0 min, no migration needed - already compliant)
### **Services (8 files) - Priority 3**
**Progress**: 2/8 (25%)
- [x] api.ts ✅ MIGRATED 2024-12-19 (0 min, no migration needed - already compliant)
@@ -241,6 +267,7 @@ export default class ComponentName extends Vue {
- [ ] deepLinks.ts
### **Utils (4 files) - Priority 4**
**Progress**: 1/4 (25%)
- [ ] LogCollector.ts
@@ -253,6 +280,7 @@ export default class ComponentName extends Vue {
## 🛠️ **Migration Tools**
### **Migration Helper Script**
```bash
# Track progress
./scripts/migration-helper.sh progress
@@ -277,6 +305,7 @@ export default class ComponentName extends Vue {
```
### **Validation Commands**
```bash
# Check for remaining databaseUtil imports
find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil"
@@ -296,12 +325,14 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 📊 **Progress Tracking**
### **Day 1 Progress**
- [ ] Phase 1: Circular dependency resolved
- [ ] Phase 2: Utility functions added
- [ ] Phase 3: Type definitions updated
- [ ] Phase 4: Testing completed
### **Day 2 Progress**
- [ ] Views migrated (0/25)
- [ ] Components migrated (0/15)
- [ ] Services migrated (0/8)
@@ -309,6 +340,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
- [ ] Validation completed
### **Overall Progress**
- **Total files to migrate**: 52
- **Files migrated**: 3
- **Progress**: 6%
@@ -318,6 +350,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 🎯 **Success Criteria**
### **Day 1 Success Criteria**
- [ ] PlatformServiceMixin has no circular dependencies
- [ ] All utility functions implemented and tested
- [ ] Type definitions complete and accurate
@@ -325,6 +358,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
- [ ] TypeScript compilation passes
### **Day 2 Success Criteria**
- [ ] 0 files importing databaseUtil
- [ ] All 52 files migrated to PlatformServiceMixin
- [ ] No runtime errors in migrated components
@@ -332,6 +366,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
- [ ] Performance maintained or improved
### **Overall Success Criteria**
- [ ] Complete elimination of databaseUtil dependency
- [ ] PlatformServiceMixin is the single source of truth for database operations
- [ ] Migration fence is fully implemented
@@ -354,14 +389,17 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 📝 **Notes & Issues**
### **Current Issues**
- None identified yet
### **Decisions Made**
- PlatformServiceMixin approach chosen over USE_DEXIE_DB constant
- Self-contained utility functions preferred over imports
- Priority order: Views → Components → Services → Utils
### **Lessons Learned**
- To be filled as migration progresses
---
@@ -369,6 +407,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 🔄 **Daily Updates**
### **Day 1 Updates**
- [ ] Start time: _____
- [ ] Phase 1 completion: _____
- [ ] Phase 2 completion: _____
@@ -377,6 +416,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
- [ ] End time: _____
### **Day 2 Updates**
- [ ] Start time: _____
- [ ] Views migration completion: _____
- [ ] Components migration completion: _____
@@ -390,16 +430,19 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 🆘 **Contingency Plans**
### **If Day 1 Takes Longer**
- Focus on core functionality first
- Defer advanced utility functions to Day 2
- Prioritize circular dependency resolution
### **If Day 2 Takes Longer**
- Focus on high-impact views first
- Batch similar components together
- Use automated scripts for common patterns
### **If Issues Arise**
- Document specific problems in Notes section
- Create targeted fixes
- Maintain backward compatibility during transition
@@ -421,4 +464,4 @@ These practices ensure maintainability, consistency, and type safety for all not
---
**Last Updated**: $(date)
**Next Review**: After each phase completion
**Next Review**: After each phase completion

3
doc/migration-quick-reference.md
View File

@@ -63,6 +63,7 @@ export default class ComponentName extends Vue {
## ✅ **Validation Checklist**
After each file migration:
- [ ] No databaseUtil imports
- [ ] PlatformServiceMixin added
- [ ] Method calls updated
@@ -91,4 +92,4 @@ npm run lint && npx tsc --noEmit
---
**Last Updated**: $(date)
**Full Documentation**: `doc/migration-progress-tracker.md`
**Full Documentation**: `doc/migration-progress-tracker.md`

33
doc/migration-readiness-summary.md
View File

@@ -11,11 +11,14 @@
## 🎯 **Migration Overview**
### **Goal**
Complete the TimeSafari database migration from Dexie to SQLite by:
1. **Day 1**: Finish PlatformServiceMixin implementation (4-6 hours)
2. **Day 2**: Migrate all 52 files to PlatformServiceMixin (6-8 hours)
### **Current Status**
- ✅ **PlatformServiceMixin**: 95% complete (1,301 lines)
- ✅ **Migration Tools**: Ready and tested
- ✅ **Documentation**: Complete and cross-machine accessible
@@ -27,22 +30,30 @@ Complete the TimeSafari database migration from Dexie to SQLite by:
## 📊 **File Breakdown**
### **Views (42 files) - Priority 1**
User-facing components that need immediate attention:
- 25 files from original list
- 17 additional files identified by migration helper
### **Components (9 files) - Priority 2**
Reusable UI components:
- FeedFilters.vue, GiftedDialog.vue, GiftedPrompts.vue
- ImageMethodDialog.vue, OfferDialog.vue, OnboardingDialog.vue
- PhotoDialog.vue, PushNotificationPermission.vue, UserNameDialog.vue
### **Services (1 file) - Priority 3**
Business logic:
- deepLinks.ts
### **Utils (3 files) - Priority 4**
Utility functions:
- util.ts, test/index.ts, PlatformServiceMixin.ts (circular dependency fix)
---
@@ -50,17 +61,21 @@ Utility functions:
## 🛠️ **Available Tools**
### **Migration Helper Script**
```bash
./scripts/migration-helper.sh [command]
```
**Commands**: progress, files, patterns, template, validate, next, all
### **Progress Tracking**
- **Main Tracker**: `doc/migration-progress-tracker.md`
- **Quick Reference**: `doc/migration-quick-reference.md`
- **Completion Plan**: `doc/platformservicemixin-completion-plan.md`
### **Validation Commands**
```bash
# Check progress
./scripts/migration-helper.sh progress
@@ -77,6 +92,7 @@ find src -name "*.vue" -o -name "*.ts" | xargs grep -l "import.*databaseUtil" |
## 🔄 **Migration Pattern**
### **Standard Template**
```typescript
// 1. Add import
import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
@@ -94,6 +110,7 @@ export default class ComponentName extends Vue {
```
### **Common Replacements**
| Old | New |
|-----|-----|
| `generateInsertStatement` | `this.$generateInsertStatement` |
@@ -109,19 +126,23 @@ export default class ComponentName extends Vue {
## 🎯 **Day 1 Plan: PlatformServiceMixin Completion**
### **Phase 1: Remove Circular Dependency (30 min)**
- Remove `memoryLogs` import from PlatformServiceMixin
- Add self-contained memoryLogs implementation
- Update logger.ts
### **Phase 2: Add Missing Functions (1 hour)**
- Add `generateInsertStatement` and `generateUpdateStatement`
- Test both utility functions
### **Phase 3: Update Types (30 min)**
- Add new methods to TypeScript interfaces
- Verify compilation
### **Phase 4: Testing (1 hour)**
- Comprehensive testing and validation
- Ensure no circular dependencies
@@ -130,17 +151,20 @@ export default class ComponentName extends Vue {
## 🎯 **Day 2 Plan: File Migration**
### **Strategy**
1. **Views First** (42 files) - High impact, user-facing
2. **Components** (9 files) - Reusable UI elements
3. **Services** (1 file) - Business logic
4. **Utils** (3 files) - Utility functions
### **Batch Processing**
- Process similar files together
- Use automated scripts for common patterns
- Validate after each batch
### **Success Criteria**
- 0 files importing databaseUtil
- All tests passing
- No runtime errors
@@ -151,12 +175,14 @@ export default class ComponentName extends Vue {
## 🚀 **Expected Benefits**
### **Immediate Benefits**
- **80% reduction** in database boilerplate code
- **Eliminated circular dependencies**
- **Centralized caching** for performance
- **Type-safe** database operations
### **Long-term Benefits**
- **Simplified testing** with mockable mixin
- **Consistent error handling** across components
- **Ready for SQLite-only mode**
@@ -167,18 +193,21 @@ export default class ComponentName extends Vue {
## 📋 **Pre-Migration Checklist**
### **Environment Ready**
- [x] Migration helper script tested and working
- [x] Progress tracking system operational
- [x] Documentation complete and accessible
- [x] Validation commands working
### **Tools Available**
- [x] Automated progress tracking
- [x] Migration pattern templates
- [x] Validation scripts
- [x] Cross-machine documentation
### **Knowledge Base**
- [x] Common replacement patterns documented
- [x] Migration templates ready
- [x] Troubleshooting guides available
@@ -191,12 +220,14 @@ export default class ComponentName extends Vue {
**All systems are ready for the 2-day migration sprint.**
### **Next Steps**
1. **Start Day 1**: Complete PlatformServiceMixin
2. **Use tracking tools**: Monitor progress with helper script
3. **Follow documentation**: Use provided templates and patterns
4. **Validate frequently**: Run checks after each phase
### **Success Metrics**
- **Day 1**: PlatformServiceMixin 100% complete, no circular dependencies
- **Day 2**: 0 files importing databaseUtil, all tests passing
- **Overall**: Ready for Phase 3 cleanup and optimization
@@ -210,4 +241,4 @@ export default class ComponentName extends Vue {
---
**Last Updated**: $(date)
**Next Review**: After Day 1 completion
**Next Review**: After Day 1 completion

33
doc/migration-roadmap-next-steps.md
View File

@@ -7,6 +7,7 @@ This document outlines the immediate next steps for completing the TimeSafari da
## Current Status Summary
### ✅ **Completed Achievements**
1. **Circular Dependencies Resolved** - No active circular dependencies blocking development
2. **PlatformServiceMixin Implemented** - Core functionality with caching and utilities
3. **Migration Tools Ready** - Data comparison and transfer utilities functional
@@ -14,6 +15,7 @@ This document outlines the immediate next steps for completing the TimeSafari da
5. **Documentation Updated** - All docs reflect current PlatformServiceMixin approach
### 🔄 **Current Phase: Phase 2 - Active Migration**
- **DatabaseUtil Migration**: 52 files still importing databaseUtil
- **Contact Migration**: Framework ready, implementation in progress
- **File-by-File Migration**: Ready to begin systematic migration
@@ -23,6 +25,7 @@ This document outlines the immediate next steps for completing the TimeSafari da
### 🔴 **Priority 1: Complete PlatformServiceMixin Independence**
#### **Step 1.1: Remove memoryLogs Dependency**
```typescript
// Current: PlatformServiceMixin imports from databaseUtil
import { memoryLogs } from "@/db/databaseUtil";
@@ -32,12 +35,15 @@ const memoryLogs: string[] = [];
```
**Files to modify**:
- `src/utils/PlatformServiceMixin.ts` - Remove import, add self-contained implementation
**Estimated time**: 30 minutes
#### **Step 1.2: Add Missing Utility Methods**
Add these methods to PlatformServiceMixin:
- `$parseJson()` - Self-contained JSON parsing
- `$generateInsertStatement()` - SQL generation
- `$generateUpdateStatement()` - SQL generation
@@ -48,6 +54,7 @@ Add these methods to PlatformServiceMixin:
### 🟡 **Priority 2: Start File-by-File Migration**
#### **Step 2.1: Migrate Critical Files First**
Based on the migration plan, start with these high-priority files:
1. **`src/App.vue`** - Main application (highest impact)
@@ -57,6 +64,7 @@ Based on the migration plan, start with these high-priority files:
5. **`src/services/deepLinks.ts`** - Service layer
**Migration pattern for each file**:
```typescript
// 1. Remove databaseUtil import
// Remove: import * as databaseUtil from "../db/databaseUtil";
@@ -82,7 +90,9 @@ Based on the migration plan, start with these high-priority files:
### 🟡 **Priority 3: Systematic File Migration**
#### **Step 3.1: Migrate High-Usage Components (15 files)**
Target components with databaseUtil imports:
- `PhotoDialog.vue`
- `FeedFilters.vue`
- `UserNameDialog.vue`
@@ -97,7 +107,9 @@ Target components with databaseUtil imports:
**Estimated time**: 15-30 hours
#### **Step 3.2: Migrate High-Usage Views (20 files)**
Target views with databaseUtil imports:
- `IdentitySwitcherView.vue`
- `ContactEditView.vue`
- `ContactGiftingView.vue`
@@ -113,6 +125,7 @@ Target views with databaseUtil imports:
**Estimated time**: 20-40 hours
#### **Step 3.3: Migrate Remaining Files (27 files)**
Complete migration of all remaining files with databaseUtil imports.
**Estimated time**: 27-54 hours
@@ -120,6 +133,7 @@ Complete migration of all remaining files with databaseUtil imports.
### 🟢 **Priority 4: Contact Migration Completion**
#### **Step 4.1: Complete Contact Migration Framework**
- Implement contact import/export functionality
- Add contact validation and error handling
- Test contact migration with real data
@@ -127,6 +141,7 @@ Complete migration of all remaining files with databaseUtil imports.
**Estimated time**: 4-8 hours
#### **Step 4.2: User Testing and Validation**
- Test migration with various data scenarios
- Validate data integrity after migration
- Performance testing with large datasets
@@ -138,7 +153,9 @@ Complete migration of all remaining files with databaseUtil imports.
### 🔵 **Priority 5: Cleanup and Optimization**
#### **Step 5.1: Remove Unused databaseUtil Functions**
After all files are migrated:
- Remove unused functions from databaseUtil.ts
- Update TypeScript interfaces
- Clean up legacy code
@@ -146,6 +163,7 @@ After all files are migrated:
**Estimated time**: 4-8 hours
#### **Step 5.2: Performance Optimization**
- Optimize PlatformServiceMixin caching
- Add performance monitoring
- Implement database query optimization
@@ -153,6 +171,7 @@ After all files are migrated:
**Estimated time**: 8-16 hours
#### **Step 5.3: Legacy Dexie Removal**
- Remove Dexie dependencies
- Clean up migration tools
- Update build configurations
@@ -162,6 +181,7 @@ After all files are migrated:
## Migration Commands and Tools
### **Automated Migration Script**
Create a script to help with bulk migrations:
```bash
@@ -193,6 +213,7 @@ echo "Please review and test the changes"
```
### **Migration Testing Commands**
```bash
# Test individual file migration
npm run test -- --grep "ComponentName"
@@ -213,18 +234,21 @@ npx tsc --noEmit
## Risk Mitigation
### **Incremental Migration Strategy**
1. **One file at a time** - Minimize risk of breaking changes
2. **Comprehensive testing** - Test each migration thoroughly
3. **Rollback capability** - Keep databaseUtil.ts until migration complete
4. **Documentation updates** - Update docs as methods are migrated
### **Testing Strategy**
1. **Unit tests** - Test individual component functionality
2. **Integration tests** - Test database operations
3. **End-to-end tests** - Test complete user workflows
4. **Performance tests** - Ensure no performance regression
### **Rollback Plan**
1. **Git branches** - Each migration in separate branch
2. **Backup files** - Keep original files until migration verified
3. **Feature flags** - Ability to switch back to databaseUtil if needed
@@ -233,18 +257,21 @@ npx tsc --noEmit
## Success Metrics
### **Short-Term (This Week)**
- [ ] PlatformServiceMixin completely independent
- [ ] 5 critical files migrated
- [ ] No new circular dependencies
- [ ] All tests passing
### **Medium-Term (Next 2 Weeks)**
- [ ] 35+ files migrated (70% completion)
- [ ] Contact migration framework complete
- [ ] Performance maintained or improved
- [ ] User testing completed
### **Long-Term (Next Month)**
- [ ] All 52 files migrated (100% completion)
- [ ] databaseUtil.ts removed or minimal
- [ ] Legacy Dexie code removed
@@ -253,12 +280,14 @@ npx tsc --noEmit
## Resource Requirements
### **Development Time**
- **Immediate (This Week)**: 8-12 hours
- **Medium-Term (Next 2 Weeks)**: 35-70 hours
- **Long-Term (Next Month)**: 16-32 hours
- **Total Estimated**: 59-114 hours
### **Testing Time**
- **Unit Testing**: 20-30 hours
- **Integration Testing**: 10-15 hours
- **User Testing**: 8-12 hours
@@ -266,6 +295,7 @@ npx tsc --noEmit
- **Total Testing**: 43-65 hours
### **Total Project Time**
- **Development**: 59-114 hours
- **Testing**: 43-65 hours
- **Documentation**: 5-10 hours
@@ -274,6 +304,7 @@ npx tsc --noEmit
## Conclusion
The migration is well-positioned for completion with:
- ✅ **No blocking circular dependencies**
- ✅ **PlatformServiceMixin mostly complete**
- ✅ **Clear migration path defined**
@@ -287,4 +318,4 @@ The next steps focus on systematic file-by-file migration with proper testing an
**Created**: 2025-07-05
**Status**: Active Planning
**Last Updated**: 2025-07-05
**Note**: This roadmap is based on current codebase analysis and documented progress
**Note**: This roadmap is based on current codebase analysis and documented progress

2
doc/migration-security-checklist.md
View File

@@ -352,4 +352,4 @@ This security audit checklist ensures that the database migration maintains the
**Reviewed By**: _______________
**Approved By**: _______________
**Approved By**: _______________

31
doc/migration-to-wa-sqlite.md
View File

@@ -29,12 +29,15 @@ This document outlines the migration process from Dexie.js to absurd-sql for the
## Migration Architecture
### Migration Fence
The migration fence is now defined by the **PlatformServiceMixin** in `src/utils/PlatformServiceMixin.ts`:
- **PlatformServiceMixin**: Centralized database access with caching and utilities
- **Migration Tools**: Exclusive interface between legacy and new databases
- **Service Layer**: All database operations go through PlatformService
### Migration Order
The migration follows a specific order to maintain data integrity:
1. **Accounts** (foundational - contains DIDs)
@@ -45,9 +48,11 @@ The migration follows a specific order to maintain data integrity:
## ActiveDid Migration ⭐ **NEW FEATURE**
### Problem Solved
Previously, the `activeDid` setting was not migrated from Dexie to SQLite, causing users to lose their active identity after migration.
### Solution Implemented
The migration now includes a dedicated step for migrating the `activeDid`:
1. **Detection**: Identifies the `activeDid` from Dexie master settings
@@ -58,6 +63,7 @@ The migration now includes a dedicated step for migrating the `activeDid`:
### Implementation Details
#### New Function: `migrateActiveDid()`
```typescript
export async function migrateActiveDid(): Promise<MigrationResult> {
// 1. Get Dexie settings to find the activeDid
@@ -76,13 +82,17 @@ export async function migrateActiveDid(): Promise<MigrationResult> {
```
#### Enhanced `migrateSettings()` Function
The settings migration now includes activeDid handling:
- Extracts `activeDid` from Dexie master settings
- Validates account existence in SQLite
- Updates SQLite master settings with the `activeDid`
#### Updated `migrateAll()` Function
The complete migration now includes a dedicated step for activeDid:
```typescript
// Step 3: Migrate ActiveDid (depends on accounts and settings)
logger.info("[MigrationService] Step 3: Migrating activeDid...");
@@ -90,6 +100,7 @@ const activeDidResult = await migrateActiveDid();
```
### Benefits
- ✅ **User Identity Preservation**: Users maintain their active identity
- ✅ **Seamless Experience**: No need to manually select identity after migration
- ✅ **Data Consistency**: Ensures all identity-related settings are preserved
@@ -98,17 +109,20 @@ const activeDidResult = await migrateActiveDid();
## Migration Process
### Phase 1: Preparation ✅
- [x] PlatformServiceMixin implementation
- [x] Implement data comparison tools
- [x] Create migration service structure
### Phase 2: Core Migration ✅
- [x] Account migration with `importFromMnemonic`
- [x] Settings migration (excluding activeDid)
- [x] **ActiveDid migration** ⭐ **COMPLETED**
- [x] Contact migration framework
### Phase 3: Validation and Cleanup 🔄
- [ ] Comprehensive data validation
- [ ] Performance testing
- [ ] User acceptance testing
@@ -117,6 +131,7 @@ const activeDidResult = await migrateActiveDid();
## Usage
### Manual Migration
```typescript
import { migrateAll, migrateActiveDid } from '../services/indexedDBMigrationService';
@@ -128,6 +143,7 @@ const activeDidResult = await migrateActiveDid();
```
### Migration Verification
```typescript
import { compareDatabases } from '../services/indexedDBMigrationService';
@@ -136,7 +152,9 @@ console.log('Migration differences:', comparison.differences);
```
### PlatformServiceMixin Integration
After migration, use the mixin for all database operations:
```typescript
// Use mixin methods for database access
const contacts = await this.$contacts();
@@ -147,11 +165,13 @@ const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDi
## Error Handling
### ActiveDid Migration Errors
- **Missing Account**: If the `activeDid` from Dexie doesn't exist in SQLite accounts
- **Database Errors**: Connection or query failures
- **Settings Update Failures**: Issues updating SQLite master settings
### Recovery Strategies
1. **Automatic Recovery**: Migration continues even if activeDid migration fails
2. **Manual Recovery**: Users can manually select their identity after migration
3. **Fallback**: System creates new identity if none exists
@@ -159,11 +179,13 @@ const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDi
## Security Considerations
### Data Protection
- All sensitive data (mnemonics, private keys) are encrypted
- Migration preserves encryption standards
- No plaintext data exposure during migration
### Identity Verification
- ActiveDid migration validates account existence
- Prevents setting non-existent identities as active
- Maintains cryptographic integrity
@@ -171,6 +193,7 @@ const result = await this.$db("SELECT * FROM contacts WHERE did = ?", [accountDi
## Testing
### Migration Testing
```bash
# Run migration
npm run migrate
@@ -180,6 +203,7 @@ npm run test:migration
```
### ActiveDid Testing
```typescript
// Test activeDid migration specifically
const result = await migrateActiveDid();
@@ -188,6 +212,7 @@ expect(result.warnings).toContain('Successfully migrated activeDid');
```
### PlatformServiceMixin Testing
```typescript
// Test mixin integration
describe('PlatformServiceMixin', () => {
@@ -224,6 +249,7 @@ describe('PlatformServiceMixin', () => {
- Verify caching and error handling work correctly
### Debugging
```typescript
// Debug migration process
import { logger } from '../utils/logger';
@@ -245,6 +271,7 @@ logger.debug('[Migration] Migration completed:', result);
## Migration Status Checklist
### ✅ Completed
- [x] PlatformServiceMixin implementation
- [x] SQLite database service
- [x] Migration tools
@@ -253,11 +280,13 @@ logger.debug('[Migration] Migration completed:', result);
- [x] ActiveDid migration
### 🔄 In Progress
- [ ] Contact migration
- [ ] DatabaseUtil to PlatformServiceMixin migration
- [ ] File-by-file migration
### ❌ Not Started
- [ ] Legacy Dexie removal
- [ ] Final cleanup and validation
@@ -267,4 +296,4 @@ logger.debug('[Migration] Migration completed:', result);
**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
**Note**: Migration fence now implemented through PlatformServiceMixin instead of USE_DEXIE_DB constant

31
doc/platformservicemixin-completion-plan.md
View File

@@ -7,6 +7,7 @@ This document outlines the complete plan to finish PlatformServiceMixin implemen
## Current Status
### ✅ **PlatformServiceMixin - 95% Complete**
- **Core functionality**: ✅ Implemented
- **Caching system**: ✅ Implemented
- **Database methods**: ✅ Implemented
@@ -14,6 +15,7 @@ This document outlines the complete plan to finish PlatformServiceMixin implemen
- **Type definitions**: ✅ Implemented
### ⚠️ **Remaining Issues**
1. **Single circular dependency**: `memoryLogs` import from databaseUtil
2. **Missing utility functions**: `generateInsertStatement`, `generateUpdateStatement`
3. **52 files** still importing databaseUtil
@@ -25,6 +27,7 @@ This document outlines the complete plan to finish PlatformServiceMixin implemen
### **Phase 1: Remove Circular Dependency (30 minutes)**
#### **Step 1.1: Create Self-Contained memoryLogs**
```typescript
// In PlatformServiceMixin.ts - Replace line 50:
// Remove: import { memoryLogs } from "@/db/databaseUtil";
@@ -48,6 +51,7 @@ $appendToMemoryLogs(message: string): void {
```
#### **Step 1.2: Update logger.ts**
```typescript
// In logger.ts - Replace memoryLogs usage:
// Remove: import { memoryLogs } from "@/db/databaseUtil";
@@ -70,6 +74,7 @@ export function getMemoryLogs(): string[] {
### **Phase 2: Add Missing Utility Functions (1 hour)**
#### **Step 2.1: Add generateInsertStatement to PlatformServiceMixin**
```typescript
// Add to PlatformServiceMixin methods:
_generateInsertStatement(
@@ -95,6 +100,7 @@ _generateInsertStatement(
```
#### **Step 2.2: Add generateUpdateStatement to PlatformServiceMixin**
```typescript
// Add to PlatformServiceMixin methods:
_generateUpdateStatement(
@@ -129,6 +135,7 @@ _generateUpdateStatement(
```
#### **Step 2.3: Add Public Wrapper Methods**
```typescript
// Add to PlatformServiceMixin methods:
$generateInsertStatement(
@@ -151,6 +158,7 @@ $generateUpdateStatement(
### **Phase 3: Update Type Definitions (30 minutes)**
#### **Step 3.1: Update IPlatformServiceMixin Interface**
```typescript
// Add to IPlatformServiceMixin interface:
$generateInsertStatement(
@@ -167,6 +175,7 @@ $appendToMemoryLogs(message: string): void;
```
#### **Step 3.2: Update ComponentCustomProperties**
```typescript
// Add to ComponentCustomProperties interface:
$generateInsertStatement(
@@ -185,12 +194,14 @@ $appendToMemoryLogs(message: string): void;
### **Phase 4: Test PlatformServiceMixin (1 hour)**
#### **Step 4.1: Create Test Component**
```typescript
// Create test file: src/test/PlatformServiceMixin.test.ts
// Test all methods including new utility functions
```
#### **Step 4.2: Run Linting and Type Checking**
```bash
npm run lint
npx tsc --noEmit
@@ -203,6 +214,7 @@ npx tsc --noEmit
### **Migration Strategy**
#### **Priority Order:**
1. **Views** (25 files) - User-facing components
2. **Components** (15 files) - Reusable UI components
3. **Services** (8 files) - Business logic
@@ -211,6 +223,7 @@ npx tsc --noEmit
#### **Migration Pattern for Each File:**
**Step 1: Add PlatformServiceMixin**
```typescript
// Add to component imports:
import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
@@ -223,6 +236,7 @@ export default class ComponentName extends Vue {
```
**Step 2: Replace databaseUtil Imports**
```typescript
// Remove:
import {
@@ -244,6 +258,7 @@ import {
```
**Step 3: Update Method Calls**
```typescript
// Before:
const { sql, params } = generateInsertStatement(contact, 'contacts');
@@ -255,6 +270,7 @@ const { sql, params } = this.$generateInsertStatement(contact, 'contacts');
### **File Migration Checklist**
#### **Views (25 files) - Priority 1**
- [ ] QuickActionBvcEndView.vue
- [ ] ProjectsView.vue
- [ ] ClaimReportCertificateView.vue
@@ -278,6 +294,7 @@ const { sql, params } = this.$generateInsertStatement(contact, 'contacts');
- [ ] [5 more view files]
#### **Components (15 files) - Priority 2**
- [ ] ActivityListItem.vue
- [ ] AmountInput.vue
- [ ] ChoiceButtonDialog.vue
@@ -295,18 +312,21 @@ const { sql, params } = this.$generateInsertStatement(contact, 'contacts');
- [ ] IconRenderer.vue
#### **Services (8 files) - Priority 3**
- [ ] api.ts
- [ ] endorserServer.ts
- [ ] partnerServer.ts
- [ ] [5 more service files]
#### **Utils (4 files) - Priority 4**
- [ ] LogCollector.ts
- [ ] [3 more util files]
### **Migration Tools**
#### **Automated Script for Common Patterns**
```bash
#!/bin/bash
# migration-helper.sh
@@ -326,6 +346,7 @@ echo "logConsoleAndDb → this.\$logAndConsole"
```
#### **Validation Script**
```bash
#!/bin/bash
# validate-migration.sh
@@ -350,6 +371,7 @@ echo "Migration validation complete!"
## 🎯 **Success Criteria**
### **Day 1 Success Criteria:**
- [ ] PlatformServiceMixin has no circular dependencies
- [ ] All utility functions implemented and tested
- [ ] Type definitions complete and accurate
@@ -357,6 +379,7 @@ echo "Migration validation complete!"
- [ ] TypeScript compilation passes
### **Day 2 Success Criteria:**
- [ ] 0 files importing databaseUtil
- [ ] All 52 files migrated to PlatformServiceMixin
- [ ] No runtime errors in migrated components
@@ -364,6 +387,7 @@ echo "Migration validation complete!"
- [ ] Performance maintained or improved
### **Overall Success Criteria:**
- [ ] Complete elimination of databaseUtil dependency
- [ ] PlatformServiceMixin is the single source of truth for database operations
- [ ] Migration fence is fully implemented
@@ -386,12 +410,14 @@ echo "Migration validation complete!"
## 📋 **Daily Progress Tracking**
### **Day 1 Progress:**
- [ ] Phase 1: Circular dependency resolved
- [ ] Phase 2: Utility functions added
- [ ] Phase 3: Type definitions updated
- [ ] Phase 4: Testing completed
### **Day 2 Progress:**
- [ ] Views migrated (0/25)
- [ ] Components migrated (0/15)
- [ ] Services migrated (0/8)
@@ -403,16 +429,19 @@ echo "Migration validation complete!"
## 🆘 **Contingency Plans**
### **If Day 1 Takes Longer:**
- Focus on core functionality first
- Defer advanced utility functions to Day 2
- Prioritize circular dependency resolution
### **If Day 2 Takes Longer:**
- Focus on high-impact views first
- Batch similar components together
- Use automated scripts for common patterns
### **If Issues Arise:**
- Document specific problems
- Create targeted fixes
- Maintain backward compatibility during transition
- Maintain backward compatibility during transition

30
doc/qr-code-implementation-guide.md
View File

@@ -7,6 +7,7 @@ This document describes the QR code scanning and generation implementation in th
## Architecture
### Directory Structure
```
src/
├── services/
@@ -74,6 +75,7 @@ interface QRScannerOptions {
### Platform-Specific Implementations
#### Mobile (Capacitor)
- Uses `@capacitor-mlkit/barcode-scanning`
- Native camera access through platform APIs
- Optimized for mobile performance
@@ -82,6 +84,7 @@ interface QRScannerOptions {
- Back camera preferred for scanning
Configuration:
```typescript
// capacitor.config.ts
const config: CapacitorConfig = {
@@ -105,6 +108,7 @@ const config: CapacitorConfig = {
```
#### Web
- Uses browser's MediaDevices API
- Vue.js components for UI
- EventEmitter for stream management
@@ -116,6 +120,7 @@ const config: CapacitorConfig = {
### View Components
#### ContactQRScanView
- Dedicated view for scanning QR codes
- Full-screen camera interface
- Simple UI focused on scanning
@@ -123,6 +128,7 @@ const config: CapacitorConfig = {
- Streamlined scanning experience
#### ContactQRScanShowView
- Combined view for QR code display and scanning
- Shows user's own QR code
- Handles user registration status
@@ -160,6 +166,7 @@ const config: CapacitorConfig = {
## Build Configuration
### Common Vite Configuration
```typescript
// vite.config.common.mts
export async function createBuildConfig(mode: string) {
@@ -183,6 +190,7 @@ export async function createBuildConfig(mode: string) {
```
### Platform-Specific Builds
```json
{
"scripts": {
@@ -196,6 +204,7 @@ export async function createBuildConfig(mode: string) {
## Error Handling
### Common Error Scenarios
1. No camera found
2. Permission denied
3. Camera in use by another application
@@ -207,6 +216,7 @@ export async function createBuildConfig(mode: string) {
9. Network connectivity issues
### Error Response
- User-friendly error messages
- Troubleshooting tips
- Clear instructions for resolution
@@ -215,6 +225,7 @@ export async function createBuildConfig(mode: string) {
## Security Considerations
### QR Code Security
- Encryption of contact data
- Timestamp validation
- Version checking
@@ -222,6 +233,7 @@ export async function createBuildConfig(mode: string) {
- Rate limiting for scans
### Data Protection
- Secure transmission of contact data
- Validation of QR code authenticity
- Prevention of duplicate scans
@@ -231,6 +243,7 @@ export async function createBuildConfig(mode: string) {
## Best Practices
### Camera Access
1. Always check for camera availability
2. Request permissions explicitly
3. Handle all error conditions
@@ -238,6 +251,7 @@ export async function createBuildConfig(mode: string) {
5. Implement proper cleanup
### Performance
1. Optimize camera resolution
2. Implement proper resource cleanup
3. Handle camera switching efficiently
@@ -245,6 +259,7 @@ export async function createBuildConfig(mode: string) {
5. Battery usage optimization
### User Experience
1. Clear visual feedback
2. Camera preview
3. Scanning status indicators
@@ -257,6 +272,7 @@ export async function createBuildConfig(mode: string) {
## Testing
### Test Scenarios
1. Permission handling
2. Camera switching
3. Error conditions
@@ -267,6 +283,7 @@ export async function createBuildConfig(mode: string) {
8. Security validation
### Test Environment
- Multiple browsers
- iOS and Android devices
- Various network conditions
@@ -275,6 +292,7 @@ export async function createBuildConfig(mode: string) {
## Dependencies
### Key Packages
- `@capacitor-mlkit/barcode-scanning`
- `qrcode-stream`
- `vue-qrcode-reader`
@@ -283,12 +301,14 @@ export async function createBuildConfig(mode: string) {
## Maintenance
### Regular Updates
- Keep dependencies updated
- Monitor platform changes
- Update documentation
- Review security patches
### Performance Monitoring
- Track memory usage
- Monitor camera performance
- Check error rates
@@ -436,6 +456,7 @@ The camera switching implementation includes comprehensive error handling:
- Camera switch timeout
2. **Error Response**
```typescript
private async handleCameraSwitch(deviceId: string): Promise<void> {
try {
@@ -460,6 +481,7 @@ The camera switching implementation includes comprehensive error handling:
The camera system maintains several states:
1. **Camera States**
```typescript
type CameraState =
| "initializing" // Camera is being initialized
@@ -529,6 +551,7 @@ The camera system maintains several states:
#### MLKit Barcode Scanner Configuration
1. **Plugin Setup**
```typescript
// capacitor.config.ts
const config: CapacitorConfig = {
@@ -552,6 +575,7 @@ The camera system maintains several states:
```
2. **Camera Management**
```typescript
// CapacitorQRScanner.ts
export class CapacitorQRScanner implements QRScannerService {
@@ -603,6 +627,7 @@ The camera system maintains several states:
```
3. **Camera State Management**
```typescript
// CapacitorQRScanner.ts
private async handleCameraState(): Promise<void> {
@@ -645,6 +670,7 @@ The camera system maintains several states:
```
4. **Error Handling**
```typescript
// CapacitorQRScanner.ts
private async handleCameraError(error: Error): Promise<void> {
@@ -737,6 +763,7 @@ The camera system maintains several states:
#### Performance Optimization
1. **Battery Usage**
```typescript
// CapacitorQRScanner.ts
private optimizeBatteryUsage(): void {
@@ -759,6 +786,7 @@ The camera system maintains several states:
```
2. **Memory Management**
```typescript
// CapacitorQRScanner.ts
private async cleanupResources(): Promise<void> {
@@ -802,4 +830,4 @@ The camera system maintains several states:
- Camera switching speed
- QR code detection speed
- App responsiveness
- Background/foreground transitions
- Background/foreground transitions

11
doc/secure-storage-implementation.md
View File

@@ -111,6 +111,7 @@ export class AbsurdSqlDatabaseService implements PlatformService {
```
Key features:
- Uses absurd-sql for SQLite in the browser
- Implements operation queuing for thread safety
- Handles initialization and connection management
@@ -143,6 +144,7 @@ async function getAccount(did: string): Promise<Account | undefined> {
When converting from Dexie.js to SQL-based implementation, follow these patterns:
1. **Database Access Pattern**
```typescript
// Before (Dexie)
const result = await db.table.where("field").equals(value).first();
@@ -161,6 +163,7 @@ When converting from Dexie.js to SQL-based implementation, follow these patterns
```
2. **Update Operations**
```typescript
// Before (Dexie)
await db.table.where("id").equals(id).modify(changes);
@@ -184,6 +187,7 @@ When converting from Dexie.js to SQL-based implementation, follow these patterns
```
3. **Insert Operations**
```typescript
// Before (Dexie)
await db.table.add(item);
@@ -202,6 +206,7 @@ When converting from Dexie.js to SQL-based implementation, follow these patterns
```
4. **Delete Operations**
```typescript
// Before (Dexie)
await db.table.where("id").equals(id).delete();
@@ -216,6 +221,7 @@ When converting from Dexie.js to SQL-based implementation, follow these patterns
```
5. **Result Processing**
```typescript
// Before (Dexie)
const items = await db.table.toArray();
@@ -247,6 +253,7 @@ await databaseUtil.logConsoleAndDb(message, showInConsole);
```
Key Considerations:
- Always use `databaseUtil.mapQueryResultToValues()` to process SQL query results
- Use utility methods from `db/index.ts` when available instead of direct SQL
- Keep Dexie fallbacks wrapped in migration period checks
@@ -254,6 +261,7 @@ Key Considerations:
- For updates/inserts/deletes, execute both SQL and Dexie operations during migration period
Example Migration:
```typescript
// Before (Dexie)
export async function updateSettings(settings: Settings): Promise<void> {
@@ -274,6 +282,7 @@ export async function updateSettings(settings: Settings): Promise<void> {
```
Remember to:
- Create database access code to use the platform service, putting it in front of the Dexie version
- Instead of removing Dexie-specific code, keep it.
@@ -330,4 +339,4 @@ it's during migration then use that result instead of the SQL code's result.
4. **Documentation**
- Add API documentation
- Create migration guides
- Document security measures
- Document security measures

14
doc/sharebufferarray_spectre_security.md
View File

@@ -4,11 +4,13 @@
## 1. Introduction to SharedArrayBuffer
### Overview
- `SharedArrayBuffer` is a JavaScript object that enables **shared memory** access between the main thread and Web Workers.
- Unlike `ArrayBuffer`, the memory is **not copied** between threads—allowing **true parallelism**.
- Paired with `Atomics`, it allows low-level memory synchronization (e.g., locks, waits).
### Example Use
```js
const sab = new SharedArrayBuffer(1024);
const sharedArray = new Uint8Array(sab);
@@ -18,6 +20,7 @@ sharedArray[0] = 42;
## 2. Browser Security Requirements
### Security Headers Required to Use SharedArrayBuffer
Modern browsers **restrict access** to `SharedArrayBuffer` due to Spectre-class vulnerabilities.
The following **HTTP headers must be set** to enable it:
@@ -28,23 +31,28 @@ Cross-Origin-Embedder-Policy: require-corp
```
### HTTPS Requirement
- Must be served over **HTTPS** (except `localhost` for dev).
- These headers enforce **cross-origin isolation**.
### Role of CORS
- CORS **alone is not sufficient**.
- However, embedded resources (like scripts and iframes) must still include proper CORS headers if they are to be loaded in a cross-origin isolated context.
## 3. Spectre Vulnerability
### What is Spectre?
- A class of **side-channel attacks** exploiting **speculative execution** in CPUs.
- Allows an attacker to read arbitrary memory from the same address space.
### Affected Architectures
- Intel, AMD, ARM — essentially **all modern processors**.
### Why It's Still a Concern
- It's a **hardware flaw**, not just a software bug.
- Can't be fully fixed in software without performance penalties.
- New Spectre **variants** (e.g., v2, RSB, BranchScope) continue to emerge.
@@ -52,16 +60,19 @@ Cross-Origin-Embedder-Policy: require-corp
## 4. Mitigations and Current Limitations
### Browser Mitigations
- **Restricted precision** for `performance.now()`.
- **Disabled or gated** access to `SharedArrayBuffer`.
- **Reduced or removed** fine-grained timers.
### OS/Hardware Mitigations
- **Kernel Page Table Isolation (KPTI)**
- **Microcode updates**
- **Retpoline** compiler mitigations
### Developer Responsibilities
- Avoid sharing sensitive data across threads unless necessary.
- Use **constant-time cryptographic functions**.
- Assume timing attacks are **still possible**.
@@ -70,10 +81,12 @@ Cross-Origin-Embedder-Policy: require-corp
## 5. Practical Development Notes
### Using SharedArrayBuffer Safely
- Ensure the site is **cross-origin isolated**:
- Serve all resources with appropriate **CORS policies** (`Cross-Origin-Resource-Policy`, `Access-Control-Allow-Origin`)
- Set the required **COOP/COEP headers**
- Validate support using:
```js
if (window.crossOriginIsolated) {
// Safe to use SharedArrayBuffer
@@ -81,6 +94,7 @@ if (window.crossOriginIsolated) {
```
### Testing and Fallback
- Provide fallbacks to `ArrayBuffer` if isolation is not available.
- Document use cases clearly (e.g., high-performance WebAssembly applications or real-time audio/video processing).

31
doc/storage-implementation-checklist.md
View File

@@ -3,6 +3,7 @@
## Core Services
### 1. Storage Service Layer
- [x] Create base `PlatformService` interface
- [x] Define common methods for all platforms
- [x] Add platform-specific method signatures
@@ -25,6 +26,7 @@
- [ ] File system access
### 2. Migration Services
- [x] Implement basic migration support
- [x] Dual-storage pattern (SQLite + Dexie)
- [x] Basic data verification
@@ -37,6 +39,7 @@
- [ ] Manual triggers
### 3. Security Layer
- [x] Basic data integrity
- [ ] Implement `EncryptionService` (planned)
- [ ] Key management
@@ -50,14 +53,17 @@
## Platform-Specific Implementation
### Web Platform
- [x] Setup absurd-sql
- [x] Install dependencies
```json
{
"@jlongster/sql.js": "^1.8.0",
"absurd-sql": "^1.8.0"
}
```
- [x] Configure VFS with IndexedDB backend
- [x] Setup worker threads
- [x] Implement operation queuing
@@ -83,6 +89,7 @@
- [x] Implement atomic operations
### iOS Platform (Planned)
- [ ] Setup SQLCipher
- [ ] Install pod dependencies
- [ ] Configure encryption
@@ -96,6 +103,7 @@
- [ ] Setup app groups
### Android Platform (Planned)
- [ ] Setup SQLCipher
- [ ] Add Gradle dependencies
- [ ] Configure encryption
@@ -109,6 +117,7 @@
- [ ] Setup file provider
### Electron Platform (Planned)
- [ ] Setup Node SQLite
- [ ] Install dependencies
- [ ] Configure IPC
@@ -124,6 +133,7 @@
## Data Models and Types
### 1. Database Schema
- [x] Define tables
```sql
@@ -166,6 +176,7 @@
### 2. Type Definitions
- [x] Create interfaces
```typescript
interface Account {
did: string;
@@ -197,6 +208,7 @@
## UI Components
### 1. Migration UI (Planned)
- [ ] Create components
- [ ] `MigrationProgress.vue`
- [ ] `MigrationError.vue`
@@ -204,6 +216,7 @@
- [ ] `MigrationStatus.vue`
### 2. Settings UI (Planned)
- [ ] Update components
- [ ] Add storage settings
- [ ] Add migration controls
@@ -211,6 +224,7 @@
- [ ] Add security settings
### 3. Error Handling UI (Planned)
- [ ] Create components
- [ ] `StorageError.vue`
- [ ] `QuotaExceeded.vue`
@@ -220,6 +234,7 @@
## Testing
### 1. Unit Tests
- [x] Basic service tests
- [x] Platform service tests
- [x] Database operation tests
@@ -227,6 +242,7 @@
- [ ] Platform detection tests (planned)
### 2. Integration Tests (Planned)
- [ ] Test migrations
- [ ] Web platform tests
- [ ] iOS platform tests
@@ -234,6 +250,7 @@
- [ ] Electron platform tests
### 3. E2E Tests (Planned)
- [ ] Test workflows
- [ ] Account management
- [ ] Settings management
@@ -243,12 +260,14 @@
## Documentation
### 1. Technical Documentation
- [x] Update architecture docs
- [x] Add API documentation
- [ ] Create migration guides (planned)
- [ ] Document security measures (planned)
### 2. User Documentation (Planned)
- [ ] Update user guides
- [ ] Add troubleshooting guides
- [ ] Create FAQ
@@ -257,12 +276,14 @@
## Deployment
### 1. Build Process
- [x] Update build scripts
- [x] Add platform-specific builds
- [ ] Configure CI/CD (planned)
- [ ] Setup automated testing (planned)
### 2. Release Process (Planned)
- [ ] Create release checklist
- [ ] Add version management
- [ ] Setup rollback procedures
@@ -271,12 +292,14 @@
## Monitoring and Analytics (Planned)
### 1. Error Tracking
- [ ] Setup error logging
- [ ] Add performance monitoring
- [ ] Configure alerts
- [ ] Create dashboards
### 2. Usage Analytics
- [ ] Add storage metrics
- [ ] Track migration success
- [ ] Monitor performance
@@ -285,12 +308,14 @@
## Security Audit (Planned)
### 1. Code Review
- [ ] Review encryption
- [ ] Check access controls
- [ ] Verify data handling
- [ ] Audit dependencies
### 2. Penetration Testing
- [ ] Test data access
- [ ] Verify encryption
- [ ] Check authentication
@@ -299,6 +324,7 @@
## Success Criteria
### 1. Performance
- [x] Query response time < 100ms
- [x] Operation queuing for thread safety
- [x] Proper initialization handling
@@ -307,6 +333,7 @@
- [ ] Memory usage < 50MB (planned)
### 2. Reliability
- [x] Basic data integrity
- [x] Operation queuing
- [ ] Automatic recovery (planned)
@@ -315,6 +342,7 @@
- [ ] Data consistency (planned)
### 3. Security
- [x] Basic data integrity
- [ ] AES-256 encryption (planned)
- [ ] Secure key storage (planned)
@@ -322,8 +350,9 @@
- [ ] Audit logging (planned)
### 4. User Experience
- [x] Basic database operations
- [ ] Smooth migration (planned)
- [ ] Clear error messages (planned)
- [ ] Progress indicators (planned)
- [ ] Recovery options (planned)
- [ ] Recovery options (planned)

115
doc/usage-guide.md
View File

@@ -53,10 +53,9 @@ header-includes:
\clearpage
# Purpose of Document
Both end-users and development team members need to know how to use TimeSafari.
Both end-users and development team members need to know how to use TimeSafari.
This document serves to show how to use every feature of the TimeSafari platform.
Sections of this document are geared specifically for software developers and quality assurance
@@ -64,7 +63,7 @@ team members.
Companion videos will also describe end-to-end workflows for the end-user.
# TimeSafari
# TimeSafari
## Overview
@@ -90,49 +89,51 @@ development environment. This section will guide you through the process.
## Prerequisites
1. Have the following installed on your local machine:
- Node.js and NPM
- A web browser. For this guide, we will use Google Chrome.
- Git
- A code editor
- Node.js and NPM
- A web browser. For this guide, we will use Google Chrome.
- Git
- A code editor
2. Create an API key on Infura. This is necessary for the Endorser API to connect to the Ethereum
blockchain.
- You can create an account on Infura [here](https://infura.io/).\
blockchain.
- You can create an account on Infura [here](https://infura.io/).\
Click "CREATE NEW API KEY" and label the key. Then click "API Keys" in the top menu bar to
be taken back to the list of keys.
Click "VIEW STATS" on the key you want to use.
Click "VIEW STATS" on the key you want to use.
![](images/01_infura-api-keys.png){ width=550px }
- Go to the key detail page. Then click "MANAGE API KEY".
- Go to the key detail page. Then click "MANAGE API KEY".
![](images/02-infura-key-detail.png){ width=550px }
- Click the copy and paste button next to the string of alphanumeric characters.\
- Click the copy and paste button next to the string of alphanumeric characters.\
This is your API, also known as your project ID.
![](images/03-infura-api-key-id.png){width=550px }
- Save this for later during the Endorser API setup. This will go in your `INFURA_PROJECT_ID`
- Save this for later during the Endorser API setup. This will go in your `INFURA_PROJECT_ID`
environment variable.
## Setup steps
### 1. Clone the following repositories from their respective Git hosts:
- [TimeSafari Frontend](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa)\
### 1. Clone the following repositories from their respective Git hosts
- [TimeSafari Frontend](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa)\
This is a Progressive Web App (PWA) built with VueJS and TypeScript.
Note that the clone command here is different from the one you would use for GitHub.
```bash
git clone git clone \
ssh://git@gitea.anomalistdesign.com:222/trent_larson/crowd-funder-for-time-pwa.git
```
- [TimeSafari Backend - Endorser API](https://github.com/trentlarson/endorser-ch)\
- [TimeSafari Backend - Endorser API](https://github.com/trentlarson/endorser-ch)\
This is a NodeJS service providing the backend for TimeSafari.
```bash
git clone git@github.com:trentlarson/endorser-ch.git
```
@@ -148,7 +149,7 @@ below to generate sample data. Then copy the test database, rename it to `-dev`
`cp ../endorser-ch-test-local.sqlite3 ../endorser-ch-dev.sqlite3` \
and rerun `npm run dev` to give yourself user #0 and others from the ETHR_CRED_DATA in [the endorser.ch test util file](https://github.com/trentlarson/endorser-ch/blob/master/test/util.js#L90)
#### Alternative 2 - boostrap single seed user
#### Alternative 2 - boostrap single seed user
In this method you will end up with two accounts in the database, one for the first boostrap user,
and the second as the primary user you will use during testing. The first user will invite the
@@ -157,26 +158,30 @@ second user to the app.
1. Install dependencies and environment variables.\
In endorser-ch install dependencies and set up environment variables to allow starting it up in
development mode.
```bash
cd endorser-ch
npm clean install # or npm ci
cp .env.local .env
```
Edit the .env file's INFURA_PROJECT_ID with the value you saved earlier in the
prerequisites.\
Then create the SQLite database by running `npm run flyway migrate` with environment variables
set correctly to select the default SQLite development user as follows.
```bash
export NODE_ENV=dev
export DBUSER=sa
export DBPASS=sasa
npm run flyway migrate
```
The first run of flyway migrate may take some time to complete because the entire Flyway
```
The first run of flyway migrate may take some time to complete because the entire Flyway
distribution must be downloaded prior to executing migrations.
Successful output looks similar to the following:
```
Database: jdbc:sqlite:../endorser-ch-dev.sqlite3 (SQLite 3.41)
Schema history table "main"."flyway_schema_history" does not exist yet
@@ -202,23 +207,23 @@ A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-c
2. Generate the first user in TimeSafari PWA and bootstrap that user in Endorser's database.\
As TimeSafari is an invite-only platform the first user must be manually bootstrapped since
no other users exist to be able to invite the first user. This first user must be added manually
to the SQLite database used by Endorser. In this setup you generate the first user from the PWA.
This user is automatically generated on first usage of the TimeSafari PWA. Bootstrapping that
to the SQLite database used by Endorser. In this setup you generate the first user from the PWA.
This user is automatically generated on first usage of the TimeSafari PWA. Bootstrapping that
user is required so that this first user can register other users.
- Change directories into `crowd-funder-for-time-pwa`
```bash
cd ..
cd crowd-funder-for-time-pwa
```
- Ensure the `.env.development` file exists and has the following values:
```env
VITE_DEFAULT_ENDORSER_API_SERVER=http://127.0.0.1:3000
```
- Install dependencies and run in dev mode. For now don't worry about configuring the app. All we
need is to generate the first root user and this happens automatically on app startup.
@@ -230,45 +235,45 @@ A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-c
- Open the app in a browser and go to the developer tools. It is recommended to use a completely
separate browser profile so you do not clear out your existing user account. We will be
completely resetting the PWA app state prior to generating the first user.
In the Developer Tools go to the Application tab.
![](images/04-pwa-chrome-devtools.png){width=350px}
![](images/04-pwa-chrome-devtools.png){width=350px}
Click the "Clear site data" button and then refresh the page.
- Click the account button in the bottom right corner of the page.
![](images/05-pwa-account-button.png){width=150px}
- This will take you to the account page titled "Your Identity" on which you can see your DID,
a `did:ethr` DID in this case.
![](images/06-pwa-account-page.png){width=350px}
- Copy the DID by selecting it and copying it to the clipboard or by clicking the copy and paste
button as shown in the image.
![](images/07-pwa-did-copied.png){width=200px}
In our case this DID is:\
`did:ethr:0xe4B783c74c8B0e229524e44d0cD898D272E02CD6`
- Add that DID to the following echoed SQL statement where it says `YOUR_DID`
- Add that DID to the following echoed SQL statement where it says `YOUR_DID`
```bash
echo "INSERT INTO registration (did, maxClaims, maxRegs, epoch)
VALUES ('YOUR_DID', 100, 10000, 1719348718092);"
| sqlite3 ./endorser-ch-dev.sqlite3
```
and run this command in the parent directory just above the `endorser-ch` directory.
It needs to be the parent directory of your `endorser-ch` repository because when
It needs to be the parent directory of your `endorser-ch` repository because when
`endorser-ch` creates the SQLite database it depends on it creates it in the parent directory
of `endorser-ch`.
- You can verify with an SQL browser tool that your record has been added to the `registration`
- You can verify with an SQL browser tool that your record has been added to the `registration`
table.
![](images/08-endorser-sqlite-row-added.png){width=350px}
@@ -285,14 +290,14 @@ A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-c
4. Create the second user by opening up a separate browser profile or incognito session, opening the
TimeSafari PWA at `http://localhost:8080`. You will see the yellow banner stating "Someone must
register you before you can give or offer."
![](images/09-pwa-second-profile-first-open.png){width=350px}
- If you want to ensure you have a fresh user account then open the developer tools, clear the
Application data as before, and then refresh the page. This will generate a new user in the
Application data as before, and then refresh the page. This will generate a new user in the
browser's IndexedDB database.
5. Go to the second users' account page to copy the DID.
![](images/10-pwa-second-user-did.png){width=350px}
6. Copy the DID and put it in the text bar on the "Your Contacts" page for the first account