crowd-funder-for-time-pwa/README.md

TimeSafari.app - Crowd-Funder for Time - PWA

Time Safari allows people to ease into collaboration: start with expressions of gratitude and expand to crowd-fund with time & money, then record and see the impact of contributions.

Database Migration Status

Current Status: The application is undergoing a migration from Dexie (IndexedDB) to SQLite using absurd-sql. This migration is in Phase 2 with a well-defined migration fence in place.

Migration Progress

• ✅ SQLite Database Service: Fully implemented with absurd-sql
• ✅ Platform Service Layer: Unified database interface across platforms
• ✅ Settings Migration: Core user settings transferred
• ✅ Account Migration: Identity and key management
• 🔄 Contact Migration: User contact data (via import interface)
• 📋 Code Cleanup: Remove unused Dexie imports

Migration Fence

The migration is controlled by a migration fence that separates legacy Dexie code from the new SQLite implementation. See Migration Fence Definition for complete details.

Key Points:

• Legacy Dexie database is disabled by default
• All database operations go through PlatformServiceMixin
• Migration tools provide controlled access to both databases
• Clear separation between legacy and new code

Migration Documentation

• Migration Guide - Complete migration process
• Migration Fence Definition - Fence boundaries and rules
• Database Migration Guide - User-facing migration tools

Roadmap

See project.task.yaml for current priorities. (Numbers at the beginning of lines are estimated hours. See taskyaml.org for details.)

Setup & Building

Quick start:

• For setup, we recommend pkgx, which installs what you need (either automatically or with the dev command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files.

npm install
npm run dev

See BUILDING.md for more details.

Tests

See TESTING.md for detailed test instructions.

Icons

Application icons are in the assets directory, processed by the capacitor-assets command.

To add a Font Awesome icon, add to main.ts and reference with font-awesome element and icon attribute with the hyphenated name.

Other

Reference Material

• Notifications can be type of toast (self-dismiss), info, success, warning, and danger. They are done via notiwind and set up in App.vue.

• Customize Vue configuration.

• If you are deploying in a subdirectory, add it to publicPath in vue.config.js, eg: publicPath: "/app/time-tracker/",

Code Organization

The project uses a centralized approach to type definitions and interfaces:

• src/interfaces/ - Contains all TypeScript interfaces and type definitions
  • deepLinks.ts - Deep linking type system and Zod validation schemas
  • give.ts - Give-related interfaces and type definitions
  • claims.ts - Claim-related interfaces and verifiable credentials
  • common.ts - Shared interfaces and utility types
  • Other domain-specific interface files

Key principles:

• All interfaces and types are defined in the interfaces folder
• Zod schemas are used for runtime validation and type generation
• Domain-specific interfaces are separated into their own files
• Common interfaces are shared through common.ts
• Type definitions are generated from Zod schemas where possible

Database Architecture

The application uses a platform-agnostic database layer with Vue mixins for service access:

• src/services/PlatformService.ts - Database interface definition
• src/services/PlatformServiceFactory.ts - Platform-specific service factory
• src/services/AbsurdSqlDatabaseService.ts - SQLite implementation
• src/utils/PlatformServiceMixin.ts - Vue mixin for database access with caching
• src/db/ - Legacy Dexie database (migration in progress)

Development Guidelines:

• Always use PlatformServiceMixin for database operations in components
• Never import Dexie directly in application code
• Test with PlatformServiceMixin for new features
• Use migration tools for data transfer between systems
• Leverage mixin's ultra-concise methods: $db(), $exec(), $one(), $contacts(), $settings()

Architecture Decision: The project uses Vue mixins over Composition API composables for platform service access. See Architecture Decisions for detailed rationale.

Kudos

Gifts make the world go 'round!

• WebStorm by JetBrains for the free open-source license
• Máximo Fernández for the 3D code and explanatory post
• Many tools & libraries such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org
• Bush 3D model
• Forest floor image
• Time Safari logo assisted by DALL-E in ChatGPT
• DiceBear and Avataaars for human-looking identicons
• Some gratitude prompts thanks to Develop Good Habits

Development Database Clearing

TimeSafari provides a simple script-based approach to clear the database for development purposes.

Quick Usage

# Run the database clearing script
./scripts/clear-database.sh

# Then restart your development server
npm run build:electron:dev  # For Electron
npm run build:web:dev       # For Web

What It Does

Electron (Desktop App)

• Automatically finds and clears the SQLite database files
• Works on Linux, macOS, and Windows
• Clears all data and forces fresh migrations on next startup

Web Browser

• Provides instructions for using custom browser data directories
• Shows manual clearing via browser DevTools
• Ensures reliable database clearing without browser complications

Safety Features

• ✅ Interactive Script: Guides you through the process
• ✅ Platform Detection: Automatically detects your OS
• ✅ Clear Instructions: Step-by-step guidance for each platform
• ✅ Safe Paths: Only clears TimeSafari-specific data

Manual Commands (if needed)

Electron Database Location

# Linux
rm -rf ~/.config/TimeSafari/*

# macOS  
rm -rf ~/Library/Application\ Support/TimeSafari/*

# Windows
rmdir /s /q %APPDATA%\TimeSafari

Web Browser (Custom Data Directory)

# Create isolated browser profile
mkdir ~/timesafari-dev-data

# Start browser with custom profile
google-chrome --user-data-dir=~/timesafari-dev-data

# Clear when needed
rm -rf ~/timesafari-dev-data

See the script for complete platform-specific instructions.