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.

Roadmap

See ClickUp for current priorities.

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 build:web:serve -- --test

To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality.

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 local database (not the claim server) 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 (environment-specific)
import { APP_SERVER } from "@/constants/app";
const shareLink = `${APP_SERVER}/deep-link/claim/123`;

// For internal operations (environment-specific)
import { APP_SERVER } from "@/constants/app";
const apiUrl = `${APP_SERVER}/api/claim/123`;

Documentation

• 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 fontawesome.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
• 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