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
3 days ago · 57ea7f67c5
1 changed files with 251 additions and 43 deletions
--- a/README.md
+++ b/README.md
@ -1,8 +1,26 @@
-# Time Safari Application
+# TimeSafari.app - Crowd-Funder for Time - PWA
-**Author**: Matthew Raymer
+[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude
-**Version**: 1.0.8-beta
+and expand to crowd-fund with time & money, then record and see the impact of contributions.
-**Description**: Time Safari Application
+
 ## 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+
+## Logging Configuration
 - npm, yarn, or pnpm
 - Git
-### 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
+# Show only errors
-npm run guard:setup  # Sets up Build Architecture Guard
+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
+# Generate/update asset configurations
-npm run build:ios:test   # Build iOS test version
+npm run assets:config
-npm run build:android:test # Build Android test version
+
-npm run build:electron:dev # Build Electron dev version
+# 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
+# Install all dependencies (required first time and after updates)
-npm run test:mobile      # Run mobile tests
+npm install
-npm run test:all         # Run all tests
+
 # 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
+## Kudos
 [Add your license information here]
---
+Gifts make the world go 'round!
-**Note**: The Build Architecture Guard is active and will block
+* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license
-commits/pushes that modify build files without proper documentation
+* [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)
-updates. See `doc/README-BUILD-GUARD.md` for complete details.
+* [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/)