docs: comprehensive build system documentation overhaul

- Expand BUILDING.md with detailed platform-specific build commands and workflows - Add comprehensive web build script documentation with environment modes and Docker support - Include complete iOS/Android build command reference with auto-run capabilities - Document Electron build patterns with code signing and packaging instructions - Add troubleshooting sections for common build issues across platforms - Streamline README.md by removing redundant build system details - Include build architecture overview with service worker and environment configuration - Add comprehensive npm script reference for all build operations - Document auto-run system and platform-specific testing workflows - Include security considerations and code signing procedures for distribution Improves developer experience with complete build system documentation and reduces onboarding friction for new contributors.
2 weeks ago · 6bc94ea014
2 changed files with 633 additions and 199 deletions
--- a/BUILDING.md
+++ b/BUILDING.md
@ -1,14 +1,12 @@
 # Building TimeSafari
-This guide explains how to build TimeSafari for different platforms.
+This guide explains how to build TimeSafari for different platforms using the comprehensive build system.
 ## Prerequisites
-For a quick dev environment setup, use [pkgx](https://pkgx.dev).
+- Node.js 18+ and npm
 - Node.js (LTS version recommended)
 - npm (comes with Node.js)
 - Git
 - For mobile builds: Xcode (macOS) or Android Studio
 - For desktop builds: Additional build tools based on your OS
 ## Forks
@ -30,13 +28,15 @@ Install dependencies:
 npm install
 ```
-## Web Dev Locally
+## Web Development
 ### Local Development
 ```bash
 npm run dev
 ```
-## Web Build for Server
+### Web Build for Server
 1. Run the production build:
@ -55,12 +55,73 @@ Install dependencies:
 npm run serve
 ```
 ### Web Build Commands
 ```bash
 # Development builds
 npm run build:web:dev              # Development build with hot reload
 npm run build:web:test             # Test environment build
 npm run build:web:prod             # Production build
 npm run build:web:serve            # Production build with serve
 # Docker builds
 npm run build:web:docker           # Docker development build
 npm run build:web:docker:test      # Docker test build
 npm run build:web:docker:prod      # Docker production build
 ```
 ### Web Build Script Details
 All web build commands use the `./scripts/build-web.sh` script, which provides:
 **Build Modes:**
 - **Development**: Starts Vite dev server with hot reload (default)
 - **Test**: Optimized for testing with minimal minification
 - **Production**: Optimized for production with full minification
 **Script Features:**
 - **Environment Validation**: Checks for Node.js, npm, npx, package.json
 - **Environment Setup**: Loads `.env` files based on build mode
 - **Clean Build**: Removes previous `dist/` directory
 - **Vite Build**: Executes `npx vite build --config vite.config.web.mts`
 - **Docker Support**: Optional Docker containerization
 - **Local Serving**: Built-in HTTP server for testing builds
 **Direct Script Usage:**
 ```bash
 # Direct script usage (no npm chaining)
 ./scripts/build-web.sh                    # Development build
 ./scripts/build-web.sh --dev              # Development build (explicit)
 ./scripts/build-web.sh --test             # Test environment build
 ./scripts/build-web.sh --prod             # Production environment build
 ./scripts/build-web.sh --docker           # Build with Docker containerization
 ./scripts/build-web.sh --docker:test      # Test environment + Docker
 ./scripts/build-web.sh --docker:prod      # Production environment + Docker
 ./scripts/build-web.sh --serve            # Build and serve locally
 ./scripts/build-web.sh --help             # Show help
 ./scripts/build-web.sh --verbose          # Enable verbose logging
 ```
 **Script Flow:**
 1. **Environment Validation**: Check prerequisites (Node.js, npm, etc.)
 2. **Environment Setup**: Load `.env` files, set NODE_ENV
 3. **Clean Dist**: Remove previous build artifacts
 4. **Vite Build**: Execute Vite with appropriate configuration
 5. **Optional Docker**: Build Docker container if requested
 6. **Optional Serve**: Start local HTTP server if requested
 **Exit Codes:**
 - `1` - Web cleanup failed
 - `2` - Environment setup failed  
 - `3` - Vite build failed
 - `4` - Docker build failed
 - `5` - Serve command failed
 - `6` - Invalid build mode
 ### Compile and minify for test & production
 * If there are DB changes: before updating the test server, open browser(s) with current version to test DB migrations.
 * `npx prettier --write ./sw_scripts/`
 * Update the ClickUp tasks & CHANGELOG.md & the version in package.json, run `npm install`.
 * Run a build to make sure package-lock version is updated, linting works, etc: `npm install && npm run build`
@ -74,7 +135,14 @@ Install dependencies:
 * For test, build the app (because test server is not yet set up to build):
 ```bash
-TIME_SAFARI_APP_TITLE="TimeSafari_Test" VITE_APP_SERVER=https://test.timesafari.app VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app VITE_PASSKEYS_ENABLED=true npm run build:web
+TIME_SAFARI_APP_TITLE="TimeSafari_Test" \
 VITE_APP_SERVER=https://test.timesafari.app \
 VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F \
 VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch \
 VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app \
 VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch \
 VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app \
 VITE_PASSKEYS_ENABLED=true npm run build:web
 ```
 ... and transfer to the test server:
@ -160,6 +228,17 @@ Run with Docker Compose:
 docker-compose up -d
 ```
 ### Docker Commands
 ```bash
 # Docker operations
 npm run docker:up                    # Start Docker services
 npm run docker:up:test              # Start test environment
 npm run docker:up:prod              # Start production environment
 npm run docker:down                 # Stop Docker services
 npm run docker:logs                 # View logs
 ```
 ### Production Deployment
 For production deployment, consider the following:
@ -204,10 +283,7 @@ docker run -d \
 ## Desktop Build (Electron)
-TimeSafari's Electron build system provides comprehensive desktop application
+TimeSafari's Electron build system provides comprehensive desktop application packaging and distribution capabilities across Windows, macOS, and Linux platforms. The system supports multiple build modes, environment configurations, and package formats.
 packaging and distribution capabilities across Windows, macOS, and Linux
 platforms. The system supports multiple build modes, environment
 configurations, and package formats.
 ### Quick Start
@ -759,6 +835,34 @@ The script handles all the necessary steps including:
 - Version number updates
 - Xcode project opening
 #### iOS Build Commands
 ```bash
 # Standard builds
 npm run build:ios                    # Standard build and open Xcode
 npm run build:ios:dev               # Development build
 npm run build:ios:test              # Test build
 npm run build:ios:prod              # Production build
 # Auto-run builds
 npm run build:ios:test:run          # Test build with auto-run
 npm run build:ios:prod:run          # Production build with auto-run
 # Debug and release builds
 npm run build:ios:debug             # Debug build
 npm run build:ios:debug:run         # Debug build with auto-run
 npm run build:ios:release           # Release build
 npm run build:ios:release:run       # Release build with auto-run
 # Additional operations
 npm run build:ios:studio            # Open in Xcode Studio
 npm run build:ios:ipa               # Generate IPA file
 npm run build:ios:clean             # Clean build artifacts
 npm run build:ios:sync              # Sync Capacitor
 npm run build:ios:assets            # Generate assets
 npm run build:ios:deploy            # Deploy to device/simulator
 ```
 #### Manual Build Process
 If you need to build manually or want to understand the individual steps:
@ -766,7 +870,6 @@ If you need to build manually or want to understand the individual steps:
 #### First-time iOS Configuration
 - Generate certificates inside XCode.
 - Right-click on App and under Signing & Capabilities set the Team.
 #### Each Release
@ -842,6 +945,55 @@ If you need to build manually or want to understand the individual steps:
 Prerequisites: Android Studio with Java SDK installed
 #### Automated Build Script
 The recommended way to build for Android is using the automated build script:
 ```bash
 # Standard build and open Android Studio
 ./scripts/build-android.sh
 # Build with specific version numbers
 ./scripts/build-android.sh --version 1.0.3 --build-number 35
 # Build without opening Android Studio (for CI/CD)
 ./scripts/build-android.sh --no-studio
 # Show all available options
 ./scripts/build-android.sh --help
 ```
 #### Android Build Commands
 ```bash
 # Standard builds
 npm run build:android                 # Standard build and open Android Studio
 npm run build:android:dev            # Development build
 npm run build:android:test           # Test build
 npm run build:android:prod           # Production build
 # Auto-run builds
 npm run build:android:test:run       # Test build with auto-run
 npm run build:android:prod:run       # Production build with auto-run
 # Debug and release builds
 npm run build:android:debug          # Debug build
 npm run build:android:debug:run      # Debug build with auto-run
 npm run build:android:release        # Release build
 npm run build:android:release:run    # Release build with auto-run
 # Additional operations
 npm run build:android:studio         # Open in Android Studio
 npm run build:android:apk            # Generate APK
 npm run build:android:aab            # Generate AAB (App Bundle)
 npm run build:android:clean          # Clean build artifacts
 npm run build:android:sync           # Sync Capacitor
 npm run build:android:assets         # Generate assets
 npm run build:android:deploy         # Deploy to device/emulator
 ```
 #### Manual Build Process
 1. Build the web assets:
   ```bash
@ -911,6 +1063,168 @@ At play.google.com/console:
 - Note that if you add testers, you have to go to "Publishing Overview" and send those changes or your (closed) testers won't see it.
 ### Capacitor Operations
 ```bash
 # Build Capacitor assets
 npm run build:capacitor
 # Sync Capacitor
 npm run build:capacitor:sync
 ```
 ## Testing
 ### Web Testing
 ```bash
 # Run web tests
 npm run test:web
 ```
 ### Mobile Testing
 ```bash
 # Run mobile tests
 npm run test:mobile
 # Android tests
 npm run test:android
 # iOS tests
 npm run test:ios
 ```
 ### Device Checks
 ```bash
 # Check Android device connection
 npm run check:android-device
 # Check iOS device/simulator
 npm run check:ios-device
 ```
 ### Test Prerequisites
 ```bash
 # Test prerequisites
 npm run test:prerequisites
 ```
 ## Auto-Run System
 The auto-run system provides automated development workflows:
 ```bash
 # Auto-run with default settings
 npm run auto-run
 # Auto-run test environment
 npm run auto-run:test
 # Auto-run production environment
 npm run auto-run:prod
 # Platform-specific auto-run
 npm run auto-run:ios
 npm run auto-run:android
 npm run auto-run:electron
 ```
 ## Cleaning
 ```bash
 # Clean Android
 npm run clean:android
 # Clean iOS
 npm run clean:ios
 # Clean Electron
 npm run clean:electron
 ```
 ## Fastlane Integration
 ### iOS Fastlane
 ```bash
 # Beta release
 npm run fastlane:ios:beta
 # App Store release
 npm run fastlane:ios:release
 ```
 ### Android Fastlane
 ```bash
 # Beta release
 npm run fastlane:android:beta
 # Play Store release
 npm run fastlane:android:release
 ```
 ## Code Quality
 ```bash
 # Lint code
 npm run lint
 # Fix linting issues
 npm run lint-fix
 ```
 ## Build Architecture
 ### Web Build Process
 1. **Environment Setup**: Load platform-specific environment variables
 2. **Asset Building**: Vite builds optimized web assets
 3. **PWA Generation**: Service worker and manifest creation
 4. **Output**: Production-ready files in `dist/` directory
 ### Electron Build Process
 1. **Web Build**: Vite builds web assets for Electron
 2. **Capacitor Sync**: Copies assets to Electron app directory
 3. **TypeScript Compile**: Compiles main process code
 4. **Native Module Rebuild**: Rebuilds native dependencies
 5. **Package Creation**: Generates platform-specific installers
 ### Mobile Build Process
 1. **Web Build**: Vite builds web assets
 2. **Capacitor Sync**: Syncs with native platforms
 3. **Asset Generation**: Creates platform-specific assets
 4. **Native Build**: Platform-specific compilation
 5. **Package Creation**: APK/IPA generation
 ## Environment Configuration
 ### Environment Files
 - `.env.development` - Development environment
 - `.env.test` - Testing environment
 - `.env.production` - Production environment
 ### Key Environment Variables
 ```bash
 # API Servers
 VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch
 VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app
 VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch
 # Platform Configuration
 VITE_PLATFORM=web|electron|capacitor
 VITE_APP_SERVER=https://timesafari.app
 # Feature Flags
 VITE_PASSKEYS_ENABLED=true
 ```
 ## Android Configuration for deep links
@ -921,8 +1235,222 @@ You must add the following intent filter to the `android/app/src/main/AndroidMan
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
-                  <data android:scheme="timesafari" />
+    <data android:scheme="https" android:host="timesafari.app" />
    <data android:scheme="http" android:host="timesafari.app" />
 </intent-filter>
 ```
 ... though when we tried that most recently it failed to 'build' the APK with: http(s) scheme and host attribute are missing, but are required for Android App Links [AppLinkUrlError]
 ## Troubleshooting
 ### Common Issues
 #### Build Failures
 ```bash
 # Clean and rebuild
 npm run clean:electron
 npm run build:electron:dev
 ```
 #### Native Module Issues
 ```bash
 # Rebuild native modules
 cd electron && npm run build
 ```
 #### Asset Issues
 ```bash
 # Regenerate assets
 npm run build:ios:assets
 npm run build:android:assets
 ```
 ### Platform-Specific Issues
 #### Windows
 - Ensure Windows Build Tools installed
 - Check NSIS installation
 - Verify code signing certificates
 #### macOS
 - Install Xcode Command Line Tools
 - Configure code signing certificates
 - Check app notarization requirements
 #### Linux
 - Install required packages (rpm-tools, etc.)
 - Check AppImage dependencies
 - Verify desktop integration
 #### iOS
 - Install Xcode and Command Line Tools
 - Configure signing certificates
 - Check provisioning profiles
 #### Android
 - Install Android Studio and SDK
 - Configure signing keys
 - Check device/emulator setup
 ## Additional Resources
 - [Electron Build Patterns](docs/electron-build-patterns.md)
 - [iOS Build Scripts](docs/ios-build-scripts.md)
 - [Android Build Scripts](docs/android-build-scripts.md)
 - [Web Build Scripts](docs/web-build-scripts.md)
 - [Build Troubleshooting](docs/build-troubleshooting.md)
 ---
 ## Appendix: Build System Organization
 ### Build Process Overview
 TimeSafari's build system follows a multi-stage process that prepares assets, combines scripts, and generates platform-specific outputs.
 #### Pre-Build Preparation
 **1. Service Worker Script Preparation**
 ```bash
 # Optional: Format third-party service worker scripts
 npx prettier --write ./sw_scripts/
 ```
 **What this does:**
 - Formats cryptographic libraries (`nacl.js`, `noble-curves.js`, `noble-hashes.js`, etc.)
 - These scripts are automatically combined during the build process
 - Improves readability and makes version control diffs cleaner
 - **Note**: This is optional and only needed when updating third-party scripts
 **2. Automatic Pre-Build Steps**
 The `prebuild` script automatically runs before any build:
 ```json
 "prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node sw_combine.js && node scripts/copy-wasm.js"
 ```
 **What happens automatically:**
 - **ESLint**: Checks and fixes code formatting in `src/`
 - **Script Combination**: `sw_combine.js` combines all `sw_scripts/*.js` files into `sw_scripts-combined.js`
 - **WASM Copy**: `copy-wasm.js` copies SQLite WASM files to `public/wasm/`
 #### Build Architecture
 **Web Build Process:**
 ```
 1. Pre-Build: ESLint + Script Combination + WASM Copy
 2. Environment Setup: Load .env files, set NODE_ENV
 3. Vite Build: Bundle web assets with PWA support
 4. Service Worker: Inject combined scripts into PWA
 5. Output: Production-ready files in dist/
 ```
 **Electron Build Process:**
 ```
 1. Web Build: Vite builds web assets for Electron
 2. Capacitor Sync: Copies assets to Electron app directory
 3. TypeScript Compile: Compiles main process code
 4. Native Module Rebuild: Rebuilds native dependencies
 5. Package Creation: Generates platform-specific installers
 ```
 **Mobile Build Process:**
 ```
 1. Web Build: Vite builds web assets
 2. Capacitor Sync: Syncs with native platforms
 3. Asset Generation: Creates platform-specific assets
 4. Native Build: Platform-specific compilation
 5. Package Creation: APK/IPA generation
 ```
 #### Service Worker Architecture
 **Script Organization:**
 - `sw_scripts/` - Individual third-party scripts
 - `sw_combine.js` - Combines scripts into single file
 - `sw_scripts-combined.js` - Combined service worker (317KB, 10K+ lines)
 - `vite.config.utils.mts` - PWA configuration using combined script
 **PWA Integration:**
 ```typescript
 // vite.config.utils.mts
 pwaConfig: {
  strategies: "injectManifest",
  filename: "sw_scripts-combined.js",  // Uses our combined script
  // ... manifest configuration
 }
 ```
 **What Gets Combined:**
 - `nacl.js` - NaCl cryptographic library
 - `noble-curves.js` - Elliptic curve cryptography (177KB)
 - `noble-hashes.js` - Cryptographic hash functions (91KB)
 - `safari-notifications.js` - Safari-specific notifications
 - `additional-scripts.js` - Additional service worker functionality
 #### Environment Configuration
 **Environment Files:**
 - `.env.development` - Development environment
 - `.env.test` - Testing environment  
 - `.env.production` - Production environment
 **Key Environment Variables:**
 ```bash
 # API Servers
 VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch
 VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app
 VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch
 # Platform Configuration
 VITE_PLATFORM=web|electron|capacitor
 VITE_APP_SERVER=https://timesafari.app
 # Feature Flags
 VITE_PASSKEYS_ENABLED=true
 ```
 #### Build Output Structure
 **Web Build:**
 ```
 dist/
 ├── index.html              # Main HTML file
 ├── assets/                 # Bundled JavaScript/CSS
 ├── sw.js                   # Service worker (injected)
 ├── manifest.webmanifest    # PWA manifest
 └── wasm/                   # SQLite WASM files
 ```
 **Electron Build:**
 ```
 electron/
 ├── app/                    # Web assets
 ├── build/                  # Compiled TypeScript
 ├── dist/                   # Distribution packages
 │   ├── TimeSafari.exe     # Windows executable
 │   ├── TimeSafari.dmg     # macOS installer
 │   ├── TimeSafari.AppImage # Linux AppImage
 │   └── TimeSafari.deb     # Debian package
 └── node_modules/           # Dependencies
 ```
 #### Manual vs Automatic Steps
 **Manual Steps (Developer Responsibility):**
 - Database migration testing
 - Service worker script formatting (optional)
 - Version updates and changelog
 - Environment-specific builds
 **Automatic Steps (Build System):**
 - Code linting and formatting
 - Script combination
 - Asset optimization
 - Package creation
 - Service worker injection
 This architecture ensures consistent builds across all platforms while providing flexibility for platform-specific optimizations and manual quality assurance steps.
--- a/README.md
+++ b/README.md
@ -45,7 +45,7 @@ npm install
 npm run dev
 ```
-See [BUILDING.md](BUILDING.md) for more details.
+See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
 ## Development Database Clearing
@ -107,99 +107,6 @@ rm -rf ~/timesafari-dev-data
 See the script for complete platform-specific instructions.
 ## Build Systems
 TimeSafari supports comprehensive build systems for all platforms with unified patterns and consistent tooling.
 ### **Quick Start Commands**
 ```bash
 # Web Development (starts dev server)
 npm run build:web:dev
 # Android Development (builds debug APK)
 npm run build:android:dev
 # iOS Development (builds debug app)
 npm run build:ios:dev
 # Electron Development (runs app directly)
 npm run build:electron:dev
 # Deploy Android to connected device
 npm run build:android:deploy
 # Deploy iOS to connected device
 npm run build:ios:deploy
 ```
 ### **Platform-Specific Builds**
 #### **Web Builds**
 - **Development**: Hot reload server at http://localhost:8080
 - **Production**: Optimized static files with PWA support
 - **Docker**: Containerized deployment images
 ```bash
 npm run build:web:dev      # Development server
 npm run build:web:prod     # Production build
 npm run build:web:docker:prod  # Docker deployment
 ```
 #### **Android Builds**
 - **Development**: Debug APK with development optimizations
 - **Production**: Release APK/AAB for app store distribution
 - **Deployment**: Direct installation to connected devices
 ```bash
 npm run build:android:dev      # Development build
 npm run build:android:prod     # Production build
 npm run build:android:deploy   # Build and deploy to device
 ```
 #### **iOS Builds**
 - **Development**: Debug app with development optimizations
 - **Production**: Release app/IPA for app store distribution
 - **Deployment**: Direct installation to connected devices
 ```bash
 npm run build:ios:dev          # Development build
 npm run build:ios:prod         # Production build
 npm run build:ios:deploy       # Build and deploy to device
 ```
 #### **Electron Builds**
 - **Development**: Runs app directly for development
 - **Packages**: Creates distributable executables
 - **Cross-Platform**: Windows, macOS, Linux support
 ```bash
 npm run build:electron:dev         # Runs app directly
 npm run build:electron:appimage:prod  # Linux AppImage
 npm run build:electron:dmg:prod    # macOS DMG
 npm run build:electron:deb:prod    # Linux DEB
 ```
 ### **Build System Features**
 - ✅ **Unified Environment Management**: Consistent dev/test/prod modes
 - ✅ **PWA Support**: Progressive Web App functionality across platforms
 - ✅ **Asset Generation**: Automatic icon and splash screen generation
 - ✅ **Docker Integration**: Containerized deployment options
 - ✅ **Performance Optimization**: Build-time and runtime optimizations
 - ✅ **Error Handling**: Comprehensive error reporting and recovery
 - ✅ **Legacy Compatibility**: Backward-compatible script aliases
 ### **Comprehensive Documentation**
 - **[Build Systems Overview](docs/build-systems-overview.md)** - Complete guide to all build systems
 - **[Web Build Scripts](docs/web-build-scripts.md)** - Web/PWA builds with Docker support
 - **[Android Build Scripts](docs/android-build-scripts.md)** - Mobile builds with device deployment
 - **[iOS Build Scripts](docs/ios-build-scripts.md)** - iOS builds with Xcode integration
 - **[Electron Build Scripts](docs/electron-build-scripts.md)** - Desktop builds with package creation
 - **[Database Clearing](docs/database-clearing.md)** - Development database management
 - **[Build Troubleshooting](docs/build-troubleshooting.md)** - Comprehensive troubleshooting guide
 ## Tests
 See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
@ -252,7 +159,6 @@ The application uses a platform-agnostic database layer with Vue mixins for serv
 **Development Guidelines**:
 - Always use `PlatformServiceMixin` for database operations in components
 - Never import Dexie directly in application code
 - 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()`