crowd-funder-from-jason/docs/build-system/core/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

```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=<platform>
PWA: automatically enabled for web platforms
VITE_GIT_HASH=<git-commit-hash>
```

### 2. **Argument Parsing**
```bash
# Consistent command-line interface
./scripts/build-<platform>.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=<git-commit-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:<platform>: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-<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