crowd-funder-for-time-pwa/.cursor/rules/app/timesafari.mdc

# Time Safari Context

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Core application context

## Project Overview

Time Safari is an application designed to foster community building through
gifts, gratitude, and collaborative projects. The app makes it easy and
intuitive for users of any age and capability to recognize contributions,
build trust networks, and organize collective action. It is built on services
that preserve privacy and data sovereignty.

## Core Goals

1. **Connect**: Make it easy, rewarding, and non-threatening for people to
   connect with others who have similar interests, and to initiate activities
   together.

2. **Reveal**: Widely advertise the great support and rewards that are being
   given and accepted freely, especially non-monetary ones, showing the impact
   gifts make in people's lives.

## Technical Foundation

### Architecture

- **Privacy-preserving claims architecture** via endorser.ch
- **Decentralized Identifiers (DIDs)**: User identities based on
  public/private key pairs stored on devices
- **Cryptographic Verification**: All claims and confirmations are
  cryptographically signed
- **User-Controlled Visibility**: Users explicitly control who can see their
  identifiers and data
- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron)

### Current Database State

- **Database**: SQLite via Absurd SQL (browser) and native SQLite
  (mobile/desktop)
- **Legacy Support**: IndexedDB (Dexie) for backward compatibility
- **Status**: Modern database architecture fully implemented

### Core Technologies

- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator
- **Styling**: TailwindCSS
- **Build**: Vite with platform-specific configs
- **Testing**: Playwright E2E, Jest unit tests
- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy)
- **State**: Pinia stores
- **Platform Services**: Abstracted behind interfaces with factory pattern

## Development Principles

### Code Organization

- **Platform Services**: Abstract platform-specific code behind interfaces
- **Service Factory**: Use `PlatformServiceFactory` for platform selection
- **Type Safety**: Strict TypeScript, no `any` types, use type guards
- **Modern Architecture**: Use current platform service patterns

### Architecture Patterns

- **Dependency Injection**: Services injected via mixins and factory pattern
- **Interface Segregation**: Small, focused interfaces over large ones
- **Composition over Inheritance**: Prefer mixins and composition
- **Single Responsibility**: Each component/service has one clear purpose

### Testing Strategy

- **E2E**: Playwright for critical user journeys
- **Unit**: Jest with F.I.R.S.T. principles
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI
- **Quality Assurance**: Comprehensive testing and validation

## Current Development Focus

### Active Development

- **Feature Development**: Build new functionality using modern platform
  services
- **Performance Optimization**: Improve app performance and user experience
- **Platform Enhancement**: Leverage platform-specific capabilities
- **Code Quality**: Maintain high standards and best practices

### Development Metrics

- **Code Quality**: High standards maintained across all platforms
- **Performance**: Optimized for all target devices
- **Testing**: Comprehensive coverage maintained
- **User Experience**: Focus on intuitive, accessible interfaces

## Platform-Specific Considerations

### Web (PWA)

- **QR Scanning**: WebInlineQRScanner
- **Deep Linking**: URL parameters
- **File System**: Limited browser APIs
- **Build**: `npm run build:web` (development build)

### Mobile (Capacitor)

- **QR Scanning**: @capacitor-mlkit/barcode-scanning
- **Deep Linking**: App URL open events
- **File System**: Capacitor Filesystem
- **Build**: `npm run build:capacitor`

### Desktop (Electron)

- **File System**: Node.js fs
- **Build**: `npm run build:electron`
- **Distribution**: AppImage, DEB, DMG packages

## Development Workflow

### Build Commands

```bash
# Web (development)
npm run build:web

# Mobile
npm run build:capacitor
npm run build:native

# Desktop
npm run build:electron
npm run build:electron:appimage
npm run build:electron:deb
npm run build:electron:dmg
```

### Testing Commands

```bash
# Web E2E
npm run test:web

# Mobile
npm run test:mobile
npm run test:android
npm run test:ios

# Type checking
npm run type-check
npm run lint-fix
```

## Key Constraints

1. **Privacy First**: User identifiers remain private except when explicitly
   shared
2. **Platform Compatibility**: Features must work across all target platforms
3. **Performance**: Must remain performant on older/simpler devices
4. **Modern Architecture**: New features should use current platform services
5. **Offline Capability**: Key functionality should work offline when feasible

## Use Cases to Support

1. **Community Building**: Tools for finding others with shared interests
2. **Project Coordination**: Easy proposal and collaboration on projects
3. **Reputation Building**: Showcasing contributions and reliability
4. **Governance**: Facilitating decision-making and collective governance

## Resources

- **Testing**: `docs/migration-testing/`
- **Architecture**: `docs/architecture-decisions.md`
- **Build Context**: `docs/build-modernization-context.md`

---

## Status: Active application context

- **Priority**: Critical
- **Estimated Effort**: Ongoing reference
- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron
- **Stakeholders**: Development team, Product team