# 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.

## Roadmap

See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities.

## 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 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](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
```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
```

## 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

```typescript
// 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](src/constants/app.ts) - Core constants

## 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 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](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
- 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/)