# 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 iOS, Android, 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
- 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
- SOLID principles
- Law of Demeter
- Composition over Inheritence
- Interface Segregation
- Fail Fast
- Principle of Least Astonishment
- Information Hiding
- Single Source of Truth
- Principle of Least Privilege
- Continuous Integration/Continuous Deployment (CI/CD)
- Ensure all components support accessibility first design
- Implement privacy-preserving features by default
- Support progressive enhancement across devices
- Enable voluntary collaboration features
- Build trust-enabling interactions
- Optimize for low resource requirements
- Support offline-first functionality where possible
- Use class-based syntax with decorators from vue-facing-decorators.
- Should attempt to maximize Lighthouse Score as close to 100 as possible.
- Use Lighthouse for performance scoring

## Vue Component Structure

- Use `@Options`, `@Ref`, `@Prop`, `@Emit`, and `@Watch` Typescript decorators for clear component structure
- Extend `Vue` class with proper type annotations for props, refs, and methods
- Use Tailwind utility classes for accessible and responsive design
- Avoid `setup()` or Composition API; use class syntax consistently
- Keep methods pure when possible; extract logic into utilities
- Ensure lifecycle methods are clearly defined inside class
- Use semantic HTML + Tailwind classes for styling
- Pinia for state management

## Vue Facing Decorators

- Ensure all Vue 3 components are written using TypeScript with strict type checking enabled.
- Always include explicit types for props, emits, and reactive properties.
- When using @Options, ensure it includes metadata like name, template, or styles.
- Use @Prop for defining props with validation and default values.
- Use @Emit for emitting events with proper payload typing.
- Use @Watch for reactive property changes, and @Ref for DOM references."
- Organize Vue 3 components with a clear structure: imports at the top, followed by @Options metadata, then class properties (props, refs, reactive state), lifecycle hooks, methods, and finally @Watch or @Emit handlers.
- Ensure all props have explicit types and optional validation.
- Use TypeScript interfaces or types for complex prop structures.
- Validate default values for props where applicable.
- Use lifecycle hooks (e.g., onMounted, onUnmounted) sparingly and document their purpose.
- Avoid side effects in lifecycle hooks unless absolutely necessary.
- Use @Emit for emitting events with strongly typed payloads.
- Ensure event names are descriptive and match the action being performed.
- Use ref or reactive for managing internal state.
- Avoid overusing reactive state for simple values. Prefer computed properties for derived state.
- Write unit tests for components using Vue Test Utils and Jest/Vitest.
- Ensure tests cover props, events, and lifecycle behavior.
- Avoid unnecessary re-renders by using v-once for static content and memoizing expensive computations with computed properties.
- Ensure components are accessible by using semantic HTML and ARIA attributes.
- Use scoped styles or CSS modules to encapsulate styles.

## es6 classes

- Use ES6 class syntax with decorators (@Options, @Prop, @Emit).
- Use modular imports and default exports.
- Use arrow functions for methods and callbacks.
- Use destructuring for props and state.
- Provide default parameters for optional props or arguments.
- Use template literals for dynamic strings.
- Use spread/rest operators for object manipulation and arguments.
- Use const/let appropriately for variable declarations.
- Use enhanced object literals for cleaner syntax.
- Use async/await for asynchronous operations.
- Add scoped styles for encapsulation.
- Ensure accessibility with semantic HTML and ARIA attributes.

## Documentation

- Include JSDoc comments for all public methods and props.
- Files must have comments explaing contents and workflow of file
- Methods and props should explain role and workflow of each