# TimeSafari.app - Crowd-Funder for Time - PWA

[Time Safari](https://timesafari.org/) 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](doc/migration-fence-definition.md) 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](doc/migration-to-wa-sqlite.md) - Complete migration process
- [Migration Fence Definition](doc/migration-fence-definition.md) - Fence boundaries and rules
- [Database Migration Guide](doc/database-migration-guide.md) - User-facing migration tools

## Roadmap

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

## Setup & Building

Quick start:

* For setup, we recommend [pkgx](https://pkgx.dev), 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.

```bash
npm install
npm run dev
```

See [BUILDING.md](BUILDING.md) for more details.

## Development Database Clearing

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

### Quick Usage
```bash
# 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**
```bash
# Linux
rm -rf ~/.config/TimeSafari/*

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

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

#### **Web Browser (Custom Data Directory)**
```bash
# 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.

## Build Systems

TimeSafari supports comprehensive build systems for all platforms with unified patterns and consistent tooling.

### **Quick Start Commands**

```bash
# Web Development (starts dev server)
npm run build:web:dev

# Android Development (builds debug APK)
npm run build:android:dev

# iOS Development (builds debug app)
npm run build:ios:dev

# Electron Development (runs app directly)
npm run build:electron:dev

# Deploy Android to connected device
npm run build:android:deploy

# Deploy iOS to connected device
npm run build:ios:deploy
```

### **Platform-Specific Builds**

#### **Web Builds**
- **Development**: Hot reload server at http://localhost:8080
- **Production**: Optimized static files with PWA support
- **Docker**: Containerized deployment images

```bash
npm run build:web:dev      # Development server
npm run build:web:prod     # Production build
npm run build:web:docker:prod  # Docker deployment
```

#### **Android Builds**
- **Development**: Debug APK with development optimizations
- **Production**: Release APK/AAB for app store distribution
- **Deployment**: Direct installation to connected devices

```bash
npm run build:android:dev      # Development build
npm run build:android:prod     # Production build
npm run build:android:deploy   # Build and deploy to device
```

#### **iOS Builds**
- **Development**: Debug app with development optimizations
- **Production**: Release app/IPA for app store distribution
- **Deployment**: Direct installation to connected devices

```bash
npm run build:ios:dev          # Development build
npm run build:ios:prod         # Production build
npm run build:ios:deploy       # Build and deploy to device
```

#### **Electron Builds**
- **Development**: Runs app directly for development
- **Packages**: Creates distributable executables
- **Cross-Platform**: Windows, macOS, Linux support

```bash
npm run build:electron:dev         # Runs app directly
npm run build:electron:appimage:prod  # Linux AppImage
npm run build:electron:dmg:prod    # macOS DMG
npm run build:electron:deb:prod    # Linux DEB
```

### **Build System Features**

- ✅ **Unified Environment Management**: Consistent dev/test/prod modes
- ✅ **PWA Support**: Progressive Web App functionality across platforms
- ✅ **Asset Generation**: Automatic icon and splash screen generation
- ✅ **Docker Integration**: Containerized deployment options
- ✅ **Performance Optimization**: Build-time and runtime optimizations
- ✅ **Error Handling**: Comprehensive error reporting and recovery
- ✅ **Legacy Compatibility**: Backward-compatible script aliases

### **Comprehensive Documentation**

- **[Build Systems Overview](docs/build-systems-overview.md)** - Complete guide to all build systems
- **[Web Build Scripts](docs/web-build-scripts.md)** - Web/PWA builds with Docker support
- **[Android Build Scripts](docs/android-build-scripts.md)** - Mobile builds with device deployment
- **[iOS Build Scripts](docs/ios-build-scripts.md)** - iOS builds with Xcode integration
- **[Electron Build Scripts](docs/electron-build-scripts.md)** - Desktop builds with package creation
- **[Database Clearing](docs/database-clearing.md)** - Development database management
- **[Build Troubleshooting](docs/build-troubleshooting.md)** - Comprehensive troubleshooting guide

## Tests

See [TESTING.md](test-playwright/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](https://www.npmjs.com/package/notiwind) and set up in App.vue.

* [Customize Vue configuration](https://cli.vuejs.org/config/).

* 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](doc/architecture-decisions.md) for detailed rationale.

### Kudos

Gifts make the world go 'round!

* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license
* [Máximo Fernández](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80)
* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org
* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439)
* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg)
* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e)
* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons
* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/)