From 57ea7f67c5dc8a67d97a6d472b647ca3b7b18e8b Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Sat, 23 Aug 2025 03:17:26 +0000 Subject: [PATCH] docs(readme): merge comprehensive project documentation and build guard Integrates Build Architecture Guard documentation, project structure overview, and contributing guidelines into README.md. Preserves existing application overview, development setup, and technical architecture sections while adding comprehensive project entry point for developers. - Adds Build Architecture Guard section with setup and usage instructions - Includes visual project structure with key directories and files - Provides contributing guidelines for build-related changes - Maintains existing application description, setup, and technical details --- README.md | 294 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 251 insertions(+), 43 deletions(-) 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/)