# TimeSafari Build Systems Overview **Author**: Matthew Raymer **Date**: 2025-07-11 **Status**: ✅ **COMPLETE** - All build systems documented and integrated ## Overview TimeSafari supports multiple platforms and build targets through a unified build system architecture. This document provides a comprehensive overview of all build systems, their purposes, and how they work together. ## Build System Architecture ### Platform Support Matrix | Platform | Build Script | Development | Testing | Production | Package Types | |----------|--------------|-------------|---------|------------|---------------| | **Web** | `build-web.sh` | ✅ Dev Server | ✅ Test Build | ✅ Prod Build | Docker Images | | **Android** | `build-android.sh` | ✅ Debug APK | ✅ Test APK | ✅ Release APK/AAB | APK, AAB | | **iOS** | `build-ios.sh` | ✅ Debug App | ✅ Test App | ✅ Release App | IPA | | **Electron** | `build-electron.sh` | ✅ Dev App | ✅ Test App | ✅ Prod App | AppImage, DEB, DMG, EXE | ### Build Script Locations ```bash scripts/ ├── build-web.sh # Web/PWA builds ├── build-android.sh # Android mobile builds ├── build-ios.sh # iOS mobile builds (future) ├── build-electron.sh # Desktop builds └── common.sh # Shared build utilities ``` ## Unified Build Pattern All build scripts follow a consistent pattern: ### 1. **Environment Setup** ```bash # Set platform-specific environment variables VITE_PLATFORM= PWA: automatically enabled for web platforms VITE_GIT_HASH= ``` ### 2. **Argument Parsing** ```bash # Consistent command-line interface ./scripts/build-.sh [--dev|--test|--prod] [options] ``` ### 3. **Build Process** ```bash # Standard build flow 1. Validate environment 2. Clean build artifacts 3. Build web assets (Vite) 4. Platform-specific build 5. Generate assets 6. Create packages (if requested) ``` ### 4. **Error Handling** ```bash # Consistent exit codes 1: Cleanup failed 2: Web build failed 3: Platform build failed 4: Asset generation failed 5: Package creation failed ``` ## Web Build System ### Purpose Builds the web application for browser and PWA deployment. ### Key Features - **Development Server**: Hot reload with Vite - **PWA Support**: Service workers and manifest generation - **Docker Integration**: Containerized deployment - **Environment Modes**: Development, test, production ### Usage Examples ```bash # Development (starts dev server) npm run build:web:dev # Production build npm run build:web:prod # Docker deployment npm run build:web:docker:prod ``` ### Output - **Development**: Vite dev server at http://localhost:8080 - **Production**: Static files in `dist/` directory - **Docker**: Containerized application image **Documentation**: [Web Build Scripts Guide](build-web-script-integration.md) ## Android Build System ### Purpose Builds Android mobile applications using Capacitor and Gradle. ### Key Features - **Capacitor Integration**: Web-to-native bridge - **Gradle Builds**: APK and AAB generation - **Asset Generation**: Icons and splash screens - **Device Deployment**: Direct APK installation ### Usage Examples ```bash # Development build npm run build:android:dev # Production APK npm run build:android:prod # Deploy to device npm run build:android:deploy ``` ### Output - **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk` - **Release APK**: `android/app/build/outputs/apk/release/app-release.apk` - **AAB Bundle**: `android/app/build/outputs/bundle/release/app-release.aab` ### Device Deployment ```bash # Automatic deployment to connected device npm run build:android:deploy # Manual deployment adb install -r android/app/build/outputs/apk/debug/app-debug.apk ``` **Documentation**: [Android Build Scripts Guide](android-build-scripts.md) ## iOS Build System ### Purpose Builds iOS mobile applications using Capacitor and Xcode. ### Key Features - **Capacitor Integration**: Web-to-native bridge - **Xcode Integration**: Native iOS builds - **Asset Generation**: Icons and splash screens - **Simulator Support**: iOS simulator testing ### Usage Examples ```bash # Development build npm run build:ios:dev # Production build npm run build:ios:prod # Open Xcode npm run build:ios:studio ``` ### Output - **Debug App**: `ios/App/build/Debug-iphonesimulator/App.app` - **Release App**: `ios/App/build/Release-iphoneos/App.app` - **IPA Package**: `ios/App/build/Release-iphoneos/App.ipa` **Documentation**: [iOS Build Scripts Guide](ios-build-scripts.md) *(Future)* ## Electron Build System ### Purpose Builds desktop applications for Windows, macOS, and Linux. ### Key Features - **Cross-Platform**: Windows, macOS, Linux support - **Package Formats**: AppImage, DEB, DMG, EXE - **Development Mode**: Direct app execution - **Single Instance**: Prevents multiple app instances ### Usage Examples ```bash # Development (runs app directly) npm run build:electron:dev # Production AppImage npm run build:electron:appimage:prod # Production DMG npm run build:electron:dmg:prod ``` ### Output - **Development**: App runs directly (no files created) - **Packages**: Executables in `electron/dist/` directory - **AppImage**: `TimeSafari-1.0.3-beta.AppImage` - **DEB**: `TimeSafari_1.0.3-beta_amd64.deb` - **DMG**: `TimeSafari-1.0.3-beta.dmg` - **EXE**: `TimeSafari Setup 1.0.3-beta.exe` **Documentation**: [Electron Build Scripts Guide](electron-build-scripts.md) ## Environment Management ### Environment Variables All build systems use consistent environment variable patterns: ```bash # Platform identification VITE_PLATFORM=web|capacitor|electron # PWA configuration PWA: automatically enabled for web platforms # Build information VITE_GIT_HASH= DEBUG_MIGRATIONS=0|1 ``` ### Environment Files ```bash .env.development # Development environment .env.test # Testing environment .env.production # Production environment ``` ### Mode-Specific Configuration Each build mode loads appropriate environment configuration: - **Development**: Local development settings - **Test**: Testing environment with test APIs - **Production**: Production environment with live APIs ## Package.json Integration ### Script Organization All build scripts are integrated into `package.json` with consistent naming: ```json { "scripts": { // Web builds "build:web": "./scripts/build-web.sh", "build:web:dev": "./scripts/build-web.sh --dev", "build:web:test": "./scripts/build-web.sh --test", "build:web:prod": "./scripts/build-web.sh --prod", // Android builds "build:android": "./scripts/build-android.sh", "build:android:dev": "./scripts/build-android.sh --dev", "build:android:test": "./scripts/build-android.sh --test", "build:android:prod": "./scripts/build-android.sh --prod", // iOS builds "build:ios": "./scripts/build-ios.sh", "build:ios:dev": "./scripts/build-ios.sh --dev", "build:ios:test": "./scripts/build-ios.sh --test", "build:ios:prod": "./scripts/build-ios.sh --prod", // Electron builds "build:electron:dev": "./scripts/build-electron.sh --dev", "build:electron:test": "./scripts/build-electron.sh --test", "build:electron:prod": "./scripts/build-electron.sh --prod" } } ``` ### Legacy Compatibility Legacy scripts are maintained as aliases for backward compatibility: ```json { "scripts": { // Legacy Android scripts (aliases) "build:capacitor:android": "npm run build:android", "build:capacitor:android:dev": "npm run build:android:dev", "build:capacitor:android:test": "npm run build:android:test", "build:capacitor:android:prod": "npm run build:android:prod" } } ``` ## Build Artifacts ### Common Artifacts All build systems generate consistent artifacts: ```bash dist/ # Web build output ├── index.html # Main HTML file ├── assets/ # Compiled assets ├── manifest.webmanifest # PWA manifest └── sw.js # Service worker android/app/build/ # Android build output ├── outputs/apk/debug/ # Debug APKs ├── outputs/apk/release/ # Release APKs └── outputs/bundle/release/ # AAB bundles ios/App/build/ # iOS build output ├── Debug-iphonesimulator/ # Debug builds └── Release-iphoneos/ # Release builds electron/dist/ # Electron packages ├── *.AppImage # Linux AppImages ├── *.deb # Linux DEB packages ├── *.dmg # macOS DMG packages └── *.exe # Windows installers ``` ### Asset Generation All platforms generate platform-specific assets: ```bash # Icons and splash screens npx capacitor-assets generate --android npx capacitor-assets generate --ios # PWA assets npx vite build --config vite.config.web.mts ``` ## Development Workflow ### Daily Development ```bash # Web development npm run build:web:dev # Starts dev server # Android development npm run build:android:dev # Builds debug APK npm run build:android:deploy # Deploy to device # Electron development npm run build:electron:dev # Runs app directly ``` ### Testing Workflow ```bash # Test all platforms npm run build:web:test npm run build:android:test npm run build:ios:test npm run build:electron:test ``` ### Production Workflow ```bash # Build all platforms for production npm run build:web:prod npm run build:android:prod npm run build:ios:prod npm run build:electron:prod # Create distribution packages npm run build:electron:appimage:prod npm run build:electron:dmg:prod npm run build:electron:deb:prod ``` ## Troubleshooting ### Common Issues #### Build Failures ```bash # Clean all build artifacts npm run clean:all # Rebuild from scratch npm run build::dev ``` #### Device Connection Issues ```bash # Check Android device connection adb devices # Check iOS device connection xcrun devicectl list devices ``` #### Environment Issues ```bash # Verify environment variables echo $VITE_PLATFORM echo "PWA: automatically enabled for web platforms" # Check environment files ls -la .env* ``` ### Debug Mode Enable verbose logging for all build scripts: ```bash # Verbose mode ./scripts/build-.sh --verbose # Debug environment DEBUG_MIGRATIONS=1 npm run build::dev ``` ## Performance Metrics ### Build Times (Typical) | Platform | Development | Production | Package | |----------|-------------|------------|---------| | **Web** | 350ms | 8s | 12s | | **Android** | 45s | 60s | 75s | | **iOS** | 60s | 90s | 120s | | **Electron** | 15s | 25s | 45s | ### Optimization Features - **Incremental Builds**: Only rebuild changed files - **Parallel Processing**: Multi-core build optimization - **Caching**: Build artifact caching - **Asset Optimization**: Image and code minification ## Security Considerations ### Build Security - **Environment Isolation**: Separate dev/test/prod environments - **Secret Management**: Secure handling of API keys - **Code Signing**: Digital signatures for packages - **Dependency Scanning**: Regular security audits ### Distribution Security - **Package Verification**: Checksum validation - **Code Signing**: Digital certificates for packages - **Update Security**: Secure update mechanisms - **Sandboxing**: Platform-specific security isolation ## Future Enhancements ### Planned Improvements - **CI/CD Integration**: Automated build pipelines - **Cross-Platform Testing**: Unified test framework - **Performance Monitoring**: Build performance tracking - **Asset Optimization**: Advanced image and code optimization ### Platform Expansion - **Windows Store**: Microsoft Store packages - **Mac App Store**: App Store distribution - **Google Play**: Play Store optimization - **App Store**: iOS App Store distribution --- **Last Updated**: 2025-07-11 **Version**: 1.0.3-beta **Status**: Production Ready