diff --git a/README.md b/README.md index 25f3ddc7..f11263dd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,26 @@ -# Time Safari Application +# TimeSafari.app - Crowd-Funder for Time - PWA -**Author**: Matthew Raymer -**Version**: 1.0.8-beta -**Description**: Time Safari Application +[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude +and expand to crowd-fund with time & money, then record and see the impact of contributions. + +## Roadmap + +See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities. + +## Setup & Building + +Quick start: + +* For setup, we recommend [pkgx](https://pkgx.dev), which installs what you need (either automatically or with the `dev` command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files. + +```bash +npm install +npm run build:web:serve -- --test +``` + +To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality. + +See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker). ## πŸ›‘οΈ Build Architecture Guard @@ -38,38 +56,240 @@ git push --no-verify **πŸ“š Full documentation**: See `doc/README-BUILD-GUARD.md` -## πŸš€ Quick Start +## Development Database Clearing -### Prerequisites +TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes. -- Node.js 18+ -- npm, yarn, or pnpm -- Git +## Logging Configuration -### Installation +TimeSafari supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control console output verbosity without modifying code. + +### Quick Usage ```bash -npm install -npm run guard:setup # Sets up Build Architecture Guard +# Show only errors +VITE_LOG_LEVEL=error npm run dev + +# Show warnings and errors +VITE_LOG_LEVEL=warn npm run dev + +# Show info, warnings, and errors (default) +VITE_LOG_LEVEL=info npm run dev + +# Show all log levels including debug +VITE_LOG_LEVEL=debug npm run dev +``` + +### Available Levels + +- **`error`**: Critical errors only +- **`warn`**: Warnings and errors (default for production web) +- **`info`**: Info, warnings, and errors (default for development/capacitor) +- **`debug`**: All log levels including verbose debugging + +See [Logging Configuration Guide](doc/logging-configuration.md) for complete details. + +### Quick Usage +```bash +# Run the database clearing script +./scripts/clear-database.sh + +# Then restart your development server +npm run build:electron:dev # For Electron +npm run build:web:dev # For Web +``` + +### What It Does + +#### **Electron (Desktop App)** +- Automatically finds and clears the SQLite database files +- Works on Linux, macOS, and Windows +- Clears all data and forces fresh migrations on next startup + +#### **Web Browser** +- Provides instructions for using custom browser data directories +- Shows manual clearing via browser DevTools +- Ensures reliable database clearing without browser complications + +### Safety Features +- βœ… **Interactive Script**: Guides you through the process +- βœ… **Platform Detection**: Automatically detects your OS +- βœ… **Clear Instructions**: Step-by-step guidance for each platform +- βœ… **Safe Paths**: Only clears TimeSafari-specific data + +### Manual Commands (if needed) + +#### **Electron Database Location** +```bash +# Linux +rm -rf ~/.config/TimeSafari/* + +# macOS +rm -rf ~/Library/Application\ Support/TimeSafari/* + +# Windows +rmdir /s /q %APPDATA%\TimeSafari ``` -### Development +#### **Web Browser (Custom Data Directory)** +```bash +# Create isolated browser profile +mkdir ~/timesafari-dev-data +``` + +## Domain Configuration + +TimeSafari uses a centralized domain configuration system to ensure consistent +URL generation across all environments. This prevents localhost URLs from +appearing in shared links during development. + +### Key Features +- βœ… **Production URLs for Sharing**: All copy link buttons use production domain +- βœ… **Environment-Specific Internal URLs**: Internal operations use appropriate + environment URLs +- βœ… **Single Point of Control**: Change domain in one place for entire app +- βœ… **Type-Safe Configuration**: Full TypeScript support + +### Quick Reference + +```typescript +// For sharing functionality (environment-specific) +import { APP_SERVER } from "@/constants/app"; +const shareLink = `${APP_SERVER}/deep-link/claim/123`; + +// For internal operations (environment-specific) +import { APP_SERVER } from "@/constants/app"; +const apiUrl = `${APP_SERVER}/api/claim/123`; +``` + +### Documentation + +- [Constants and Configuration](src/constants/app.ts) - Core constants + +## Tests + +See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions. + +## Asset Management + +TimeSafari uses a standardized asset configuration system for consistent +icon and splash screen generation across all platforms. + +### Asset Sources + +- **Single source of truth**: `resources/` directory (Capacitor default) +- **Source files**: `icon.png`, `splash.png`, `splash_dark.png` +- **Format**: PNG or SVG files for optimal quality + +### Asset Generation + +- **Configuration**: `config/assets/capacitor-assets.config.json` +- **Schema validation**: `config/assets/schema.json` +- **Build-time generation**: Platform assets generated via `capacitor-assets` +- **No VCS commits**: Generated assets are never committed to version control + +### Development Commands ```bash -npm run build:web:dev # Build web version -npm run build:ios:test # Build iOS test version -npm run build:android:test # Build Android test version -npm run build:electron:dev # Build Electron dev version +# Generate/update asset configurations +npm run assets:config + +# Validate asset configurations +npm run assets:validate + +# Clean generated platform assets (local dev only) +npm run assets:clean + +# Build with asset generation +npm run build:native ``` -### Testing +### Environment Setup & Dependencies + +Before building the application, ensure your development environment is properly +configured: ```bash -npm run test:web # Run web tests -npm run test:mobile # Run mobile tests -npm run test:all # Run all tests +# Install all dependencies (required first time and after updates) +npm install + +# Validate your development environment +npm run check:dependencies + +# Check prerequisites for testing +npm run test:prerequisites ``` +**Common Issues & Solutions**: + +- **"tsx: command not found"**: Run `npm install` to install devDependencies +- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed +- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues + +**Required Versions**: +- Node.js: 18+ (LTS recommended) +- npm: 8+ (comes with Node.js) +- Platform-specific tools: Android Studio, Xcode (for mobile builds) + +### Platform Support + +- **Android**: Adaptive icons with foreground/background, monochrome support +- **iOS**: LaunchScreen storyboard preferred, splash assets when needed +- **Web**: PWA icons generated during build to `dist/` (not committed) + +### Font Awesome Icons + +To add a Font Awesome icon, add to `fontawesome.ts` and reference with +`font-awesome` element and `icon` attribute with the hyphenated name. + +## Other + +### Reference Material + +* Notifications can be type of `toast` (self-dismiss), `info`, `success`, `warning`, and `danger`. + They are done via [notiwind](https://www.npmjs.com/package/notiwind) and set up in App.vue. + +* [Customize Vue configuration](https://cli.vuejs.org/config/). + +* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",` + +### Code Organization + +The project uses a centralized approach to type definitions and interfaces: + +* `src/interfaces/` - Contains all TypeScript interfaces and type definitions + * `deepLinks.ts` - Deep linking type system and Zod validation schemas + * `give.ts` - Give-related interfaces and type definitions + * `claims.ts` - Claim-related interfaces and verifiable credentials + * `common.ts` - Shared interfaces and utility types + * Other domain-specific interface files + +Key principles: +- All interfaces and types are defined in the interfaces folder +- Zod schemas are used for runtime validation and type generation +- Domain-specific interfaces are separated into their own files +- Common interfaces are shared through `common.ts` +- Type definitions are generated from Zod schemas where possible + +### Database Architecture + +The application uses a platform-agnostic database layer with Vue mixins for service access: + +* `src/services/PlatformService.ts` - Database interface definition +* `src/services/PlatformServiceFactory.ts` - Platform-specific service factory +* `src/services/AbsurdSqlDatabaseService.ts` - SQLite implementation +* `src/utils/PlatformServiceMixin.ts` - Vue mixin for database access with caching +* `src/db/` - Legacy Dexie database (migration in progress) + +**Development Guidelines**: + +- Always use `PlatformServiceMixin` for database operations in components +- Test with PlatformServiceMixin for new features +- Use migration tools for data transfer between systems +- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()` + +**Architecture Decision**: The project uses Vue mixins over Composition API composables for platform service access. See [Architecture Decisions](doc/architecture-decisions.md) for detailed rationale. + ## πŸ“ Project Structure ```text @@ -85,21 +305,6 @@ timesafari/ └── πŸ“„ doc/README-BUILD-GUARD.md # Guard system documentation ``` -## πŸ”§ Build System - -This project supports multiple platforms: - -- **Web**: Vite-based build with service worker support -- **Mobile**: Capacitor-based iOS and Android builds -- **Desktop**: Electron-based cross-platform desktop app -- **Docker**: Containerized deployment options - -## πŸ“š Documentation - -- **`BUILDING.md`** - Complete build system guide -- **`doc/README-BUILD-GUARD.md`** - Build Architecture Guard documentation -- **`pull_request_template.md`** - PR template for build changes - ## 🀝 Contributing 1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files @@ -107,12 +312,15 @@ This project supports multiple platforms: 3. **Test your changes** - Ensure builds work on affected platforms 4. **Document updates** - Keep BUILDING.md current and accurate -## πŸ“„ License - -[Add your license information here] +## Kudos ---- +Gifts make the world go 'round! -**Note**: The Build Architecture Guard is active and will block -commits/pushes that modify build files without proper documentation -updates. See `doc/README-BUILD-GUARD.md` for complete details. +* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license +* [MΓ‘ximo FernΓ‘ndez](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80) +* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org +* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439) +* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg) +* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e) +* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons +* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/)