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 comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
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
Domain Configuration
TimeSafari uses a centralized domain configuration system to ensure consistent URL generation across all environments. This prevents localhost URLs from appearing in shared links during development.
Key Features
- ✅ Production URLs for Sharing: All copy link buttons use production domain
- ✅ Environment-Specific Internal URLs: Internal operations use appropriate environment URLs
- ✅ Single Point of Control: Change domain in one place for entire app
- ✅ Type-Safe Configuration: Full TypeScript support
Quick Reference
// For sharing functionality (always production)
import { PROD_SHARE_DOMAIN } from "@/constants/app";
const shareLink = `${PROD_SHARE_DOMAIN}/deep-link/claim/123`;
// For internal operations (environment-specific)
import { APP_SERVER } from "@/constants/app";
const apiUrl = `${APP_SERVER}/api/claim/123`;
Documentation
- Domain Configuration System - Complete guide
- Constants and Configuration - Core constants
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
, anddanger
. They are done via notiwind and set up in App.vue. -
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 definitionsdeepLinks.ts
- Deep linking type system and Zod validation schemasgive.ts
- Give-related interfaces and type definitionsclaims.ts
- Claim-related interfaces and verifiable credentialscommon.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 definitionsrc/services/PlatformServiceFactory.ts
- Platform-specific service factorysrc/services/AbsurdSqlDatabaseService.ts
- SQLite implementationsrc/utils/PlatformServiceMixin.ts
- Vue mixin for database access with cachingsrc/db/
- Legacy Dexie database (migration in progress)
Development Guidelines:
- Always use
PlatformServiceMixin
for database operations in components - 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