crowd-funder-for-time-pwa/README-context.md

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

• 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

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

Continuous Integration/Continuous Deployment (CI/CD)

• Automated testing on every commit
• Consistent build process across platforms
• Automated deployment pipelines
• Quality gates for code merging
• Environment-specific configurations

This expanded documentation provides:

1. Clear principles for development
2. Practical implementation guidelines
3. Real-world examples
4. TypeScript integration
5. Best practices for Time Safari

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