crowd-funder-for-time-pwa/docs/build-systems-overview.md

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

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

# Set platform-specific environment variables
VITE_PLATFORM=<platform>
PWA: automatically enabled for web platforms
VITE_GIT_HASH=<git-commit-hash>

2. Argument Parsing

# Consistent command-line interface
./scripts/build-<platform>.sh [--dev|--test|--prod] [options]

3. Build Process

# 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

# 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

# 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

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

# 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

# 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

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

# 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 (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

# 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

Environment Management

Environment Variables

All build systems use consistent environment variable patterns:

# Platform identification
VITE_PLATFORM=web|capacitor|electron

# PWA configuration
PWA: automatically enabled for web platforms

# Build information
VITE_GIT_HASH=<git-commit-hash>
DEBUG_MIGRATIONS=0|1

Environment Files

.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:

{
  "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:

{
  "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:

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:

# 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

# 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

# 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

# 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

# Clean all build artifacts
npm run clean:all

# Rebuild from scratch
npm run build:<platform>:dev

Device Connection Issues

# Check Android device connection
adb devices

# Check iOS device connection
xcrun devicectl list devices

Environment Issues

# 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:

# Verbose mode
./scripts/build-<platform>.sh --verbose

# Debug environment
DEBUG_MIGRATIONS=1 npm run build:<platform>: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