From b9ca59a718016b55330c4dd934b2baeef76bf601 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Sat, 23 Aug 2025 08:11:07 +0000 Subject: [PATCH] rules(timesafari): make platform philosophy always active --- .cursor/rules/app/timesafari.mdc | 184 +++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/.cursor/rules/app/timesafari.mdc b/.cursor/rules/app/timesafari.mdc index ccc37996..513954c0 100644 --- a/.cursor/rules/app/timesafari.mdc +++ b/.cursor/rules/app/timesafari.mdc @@ -1,3 +1,187 @@ +--- +alwaysApply: true +--- +# 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 # Time Safari Context **Author**: Matthew Raymer