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

---
description:
globs:
alwaysApply: true
---
# Time Safari Context

## Project Overview

Time Safari is an application designed to foster community building through gifts,
gratitude, and collaborative projects. The app should make it extremely 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.

The ultimate goals of Time Safari are two-fold:

1. **Connect** Make it easy, rewarding, and non-threatening for people to
connect with others who have similar interests, and to initiate activities
together. This helps people accomplish and learn from other individuals in
less-structured environments; moreover, it helps them discover who they want
to continue to support and with whom they want to maintain relationships.

2. **Reveal** Widely advertise the great support and rewards that are being
given and accepted freely, especially non-monetary ones. Using visuals and text,
display the kind of impact that gifts are making in the lives of others. Also
show useful and engaging reports of project statistics and personal accomplishments.


## Core Approaches

Time Safari should help everyday users build meaningful connections and organize
collective efforts by:

1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts
and contributions people give to each other and their communities.

2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask
for or propose help on projects and interests that matter to them.

3. **Building Trust Networks**: Enabling users to maintain their network and activity
visibility. Developing reputation through verified contributions and references,
which can be selectively shown to others outside the network.

4. **Preserving Privacy**: Ensuring personal identifiers are only shared with
explicitly authorized contacts, allowing private individuals including children
to participate safely.

5. **Engaging Content**: Displaying people's records in compelling stories, and
highlighting those projects that are lifting people's lives long-term, both in
physical support and in emotional-spiritual-creative thriving.


## Technical Foundation

This application is built on a privacy-preserving claims architecture (via
endorser.ch) with these key characteristics:

- **Decentralized Identifiers (DIDs)**: User identities are based on public/private
key pairs stored on their devices
- **Cryptographic Verification**: All claims and confirmations are
cryptographically signed
- **User-Controlled Visibility**: Users explicitly control who can see their
identifiers and data
- **Merkle-Chained Claims**: Claims are cryptographically chained for verification
and integrity
- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron
and CEFPython), and web browsers

## User Journey

The typical progression of usage follows these stages:

1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude
for gifts received, building a foundation of acknowledgment.

2. **Project Proposals**: Users propose projects and ideas, reaching out to connect
with others who share similar interests.

3. **Action Triggers**: Offers of help serve as triggers and motivations to execute
proposed projects, moving from ideas to action.

## Context for LLM Development

When developing new functionality for Time Safari, consider these design principles:

1. **Accessibility First**: Features should be usable by non-technical users with
minimal learning curve.

2. **Privacy by Design**: All features must respect user privacy and data sovereignty.

3. **Progressive Enhancement**: Core functionality should work across all devices,
with richer experiences where supported.

4. **Voluntary Collaboration**: The system should enable but never coerce participation.

5. **Trust Building**: Features should help build verifiable trust between users.

6. **Network Effects**: Consider how features scale as more users join the platform.

7. **Low Resource Requirements**: The system should be lightweight enough to run
on inexpensive devices users already own.

## Use Cases to Support

LLM development should focus on enhancing these key use cases:

1. **Community Building**: Tools that help people find others with shared
interests and values.

2. **Project Coordination**: Features that make it easy to propose collaborative
projects and to submit suggestions and offers to existing ones.

3. **Reputation Building**: Methods for users to showcase their contributions
and reliability, in contexts where they explicitly reveal that information.

4. **Governance Experimentation**: Features that facilitate decision-making and
collective governance.

## Constraints

When developing new features, be mindful of these constraints:

1. **Privacy Preservation**: User identifiers must remain private except when
explicitly shared.

2. **Platform Limitations**: Features must work within the constraints of the target
app platforms, while aiming to leverage the best platform technology available.

3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch
API capabilities.

4. **Performance on Low-End Devices**: The application should remain performant
on older/simpler devices.

5. **Offline-First When Possible**: Key functionality should work offline when feasible.

## Project Technologies

- Typescript using ES6 classes using vue-facing-decorator
- TailwindCSS
- Vite Build Tool
- Playwright E2E testing
- IndexDB
- Camera, Image uploads, QR Code reader, ...

## Mobile Features

- Deep Linking
- Local Notifications via a custom Capacitor plugin

## Project Architecture

- The application must work on web browser, PWA (Progressive Web Application),
  desktop via Electron, and mobile via Capacitor
- Building for each platform is managed via Vite

## Core Development Principles

### DRY development

- **Code Reuse**
  - Extract common functionality into utility functions
  - Create reusable components for UI patterns
  - Implement service classes for shared business logic
  - Use mixins for cross-cutting concerns
  - Leverage TypeScript interfaces for shared type definitions

- **Component Patterns**
  - Create base components for common UI elements
  - Implement higher-order components for shared behavior
  - Use slot patterns for flexible component composition
  - Create composable services for business logic
  - Implement factory patterns for component creation

- **State Management**
  - Centralize state in Pinia stores
  - Use computed properties for derived state
  - Implement shared state selectors
  - Create reusable state mutations
  - Use action creators for common operations

- **Error Handling**
  - Implement centralized error handling
  - Create reusable error components
  - Use error boundary components
  - Implement consistent error logging
  - Create error type definitions

- **Type Definitions**
  - Create shared interfaces for common data structures
  - Use type aliases for complex types
  - Implement generic types for reusable components
  - Create utility types for common patterns
  - Use discriminated unions for state management

- **API Integration**
  - Create reusable API client classes
  - Implement request/response interceptors
  - Use consistent error handling patterns
  - Create type-safe API endpoints
  - Implement caching strategies

- **Platform Services**
  - Abstract platform-specific code behind interfaces
  - Create platform-agnostic service layers
  - Implement feature detection
  - Use dependency injection for services
  - Create service factories

- **Testing**
  - Create reusable test utilities
  - Implement test factories
  - Use shared test configurations
  - Create reusable test helpers
  - Implement consistent test patterns
  - F.I.R.S.T. (for Unit Tests)
    F – Fast
    I – Independent
    R – Repeatable
    S – Self-validating
    T – Timely

### SOLID Principles

- **Single Responsibility**: Each class/component should have only one reason to
  change
  - Components should focus on one specific feature (e.g., QR scanning, DID management)
  - Services should handle one type of functionality (e.g., platform services,
    crypto services)
  - Utilities should provide focused helper functions

- **Open/Closed**: Software entities should be open for extension but closed for
  modification
  - Use interfaces for service definitions
  - Implement plugin architecture for platform-specific features
  - Allow component behavior extension through props and events

- **Liskov Substitution**: Objects should be replaceable with their subtypes
  - Platform services should work consistently across web/mobile
  - Authentication providers should be interchangeable
  - Storage implementations should be swappable

- **Interface Segregation**: Clients shouldn't depend on interfaces they don't use
  - Break down large service interfaces into smaller, focused ones
  - Component props should be minimal and purposeful
  - Event emissions should be specific and targeted

- **Dependency Inversion**: High-level modules shouldn't depend on low-level modules
  - Use dependency injection for services
  - Abstract platform-specific code behind interfaces
  - Implement factory patterns for component creation

### Law of Demeter

- Components should only communicate with immediate dependencies
- Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`)
- Use mediator patterns for complex component interactions
- Implement facade patterns for subsystem access
- Keep component communication through defined events and props

### Composition over Inheritance

- Prefer building components through composition
- Use mixins for shared functionality
- Implement feature toggles through props
- Create higher-order components for common patterns
- Use service composition for complex features

### Interface Segregation

- Define clear interfaces for services
- Keep component APIs minimal and focused
- Split large interfaces into smaller, specific ones
- Use TypeScript interfaces for type definitions
- Implement role-based interfaces for different use cases

### Fail Fast

- Validate inputs early in the process
- Use TypeScript strict mode
- Implement comprehensive error handling
- Add runtime checks for critical operations
- Use assertions for development-time validation

### Principle of Least Astonishment

- Follow Vue.js conventions consistently
- Use familiar naming patterns
- Implement predictable component behaviors
- Maintain consistent error handling
- Keep UI interactions intuitive

### Information Hiding

- Encapsulate implementation details
- Use private class members
- Implement proper access modifiers
- Hide complex logic behind simple interfaces
- Use TypeScript's access modifiers effectively

### Single Source of Truth

- Use Pinia for state management
- Maintain one source for user data
- Centralize configuration management
- Use computed properties for derived state
- Implement proper state synchronization

### Principle of Least Privilege

- Implement proper access control
- Use minimal required permissions
- Follow privacy-by-design principles
- Restrict component access to necessary data
- Implement proper authentication/authorization