# Android Build Scripts Documentation

**Author**: Matthew Raymer
**Date**: 2025-07-11
**Status**: ✅ **COMPLETE** - Full Android build system integration

## Overview

The Android build system for TimeSafari has been integrated with the Vite
mode-based pattern, providing consistent environment management and flexible
build options across development, testing, and production environments.

**Note:** All Android builds should be invoked via `npm run build:android*` scripts for consistency. The legacy `build:capacitor:android*` scripts are now aliases for the corresponding `build:android*` scripts.

## Build Script Integration

### Package.json Scripts

The Android build system is fully integrated into `package.json` with the
following scripts:

#### Basic Build Commands

```bash
# Development builds (defaults to --mode development)
npm run build:android:dev      # Development build
npm run build:android:test     # Testing build
npm run build:android:prod     # Production build
```

#### Build Type Commands

```bash
# Debug builds
npm run build:android:debug    # Debug APK build

# Release builds
npm run build:android:release  # Release APK build
```

#### Specialized Commands

```bash
# Android Studio integration
npm run build:android:studio   # Build + open Android Studio

# Package builds
npm run build:android:apk      # Build APK file
npm run build:android:aab      # Build AAB (Android App Bundle)

# Utility commands
npm run build:android:clean    # Clean build artifacts only
npm run build:android:sync     # Sync Capacitor only
npm run build:android:assets   # Generate assets only
```

#### Legacy Command

```bash
# Original script (maintains backward compatibility)
npm run build:android          # Full build process
```

## Script Usage

### Direct Script Usage

The `build-android.sh` script supports comprehensive command-line options:

```bash
# Basic usage
./scripts/build-android.sh [options]

# Environment-specific builds
./scripts/build-android.sh --dev --studio    # Development + open studio
./scripts/build-android.sh --test --apk      # Testing APK build
./scripts/build-android.sh --prod --aab      # Production AAB build

# Utility operations
./scripts/build-android.sh --clean           # Clean only
./scripts/build-android.sh --sync            # Sync only
./scripts/build-android.sh --assets          # Assets only
```

### Command-Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--dev`, `--development` | Build for development environment | ✅ |
| `--test` | Build for testing environment | |
| `--prod`, `--production` | Build for production environment | |
| `--debug` | Build debug APK | ✅ |
| `--release` | Build release APK | |
| `--studio` | Open Android Studio after build | |
| `--apk` | Build APK file | |
| `--aab` | Build AAB (Android App Bundle) | |
| `--clean` | Clean build artifacts only | |
| `--sync` | Sync Capacitor only | |
| `--assets` | Generate assets only | |
| `-h`, `--help` | Show help message | |
| `-v`, `--verbose` | Enable verbose logging | |

## Build Process

### Complete Build Flow

1. **Resource Check**: Validate Android resources
2. **Cleanup**: Clean Android app and build artifacts
3. **Capacitor Build**: Build web assets with environment-specific mode
4. **Gradle Clean**: Clean Gradle build cache
5. **Gradle Build**: Assemble debug/release APK
6. **Capacitor Sync**: Sync web assets to Android platform
7. **Asset Generation**: Generate Android-specific assets
8. **Package Build**: Build APK/AAB if requested
9. **Studio Launch**: Open Android Studio if requested

### Environment-Specific Builds

#### Development Environment (`--dev`)

```bash
# Uses --mode development
npm run build:capacitor
# Builds with development optimizations and debugging enabled
```

#### Testing Environment (`--test`)

```bash
# Uses --mode test
npm run build:capacitor -- --mode test
# Builds with testing configurations and test API endpoints
```

#### Production Environment (`--prod`)

```bash
# Uses --mode production
npm run build:capacitor -- --mode production
# Builds with production optimizations and live API endpoints
```

## Build Artifacts

### APK Files

- **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk`
- **Release APK**: `android/app/build/outputs/apk/release/app-release.apk`

### AAB Files

- **Release AAB**: `android/app/build/outputs/bundle/release/app-release.aab`

### Build Locations

```bash
# APK files
android/app/build/outputs/apk/debug/
android/app/build/outputs/apk/release/

# AAB files
android/app/build/outputs/bundle/release/

# Gradle build cache
android/app/build/
android/.gradle/
```

## Environment Variables

The build system automatically sets environment variables based on the build
type:

### Capacitor Environment

```bash
VITE_PLATFORM=capacitor
VITE_PWA_ENABLED=false
VITE_DISABLE_PWA=true
DEBUG_MIGRATIONS=0
```

### Git Integration

```bash
VITE_GIT_HASH=<git-commit-hash>
# Automatically set from current git commit
```

## Error Handling

### Exit Codes

| Code | Description |
|------|-------------|
| 1 | Android cleanup failed |
| 2 | Web build failed |
| 3 | Capacitor build failed |
| 4 | Gradle clean failed |
| 5 | Gradle assemble failed |
| 6 | Capacitor sync failed |
| 7 | Asset generation failed |
| 8 | Android Studio launch failed |
| 9 | Resource check failed |

### Common Issues

#### Resource Check Failures

```bash
# Resource check may find issues but continues build
log_warning "Resource check found issues, but continuing with build..."
```

#### Gradle Build Failures

```bash
# Check Android SDK and build tools
./android/gradlew --version
# Verify JAVA_HOME is set correctly
echo $JAVA_HOME
```

## Integration with Capacitor

### Capacitor Sync Process

```bash
# Full sync (all platforms)
npx cap sync

# Android-specific sync
npx cap sync android
```

### Asset Generation

```bash
# Generate Android-specific assets
npx capacitor-assets generate --android
```

### Android Studio Integration

```bash
# Open Android Studio with project
npx cap open android
```

## Development Workflow

### Typical Development Cycle

```bash
# 1. Make code changes
# 2. Build for development
npm run build:android:dev

# 3. Open Android Studio for debugging
npm run build:android:studio

# 4. Test on device/emulator
# 5. Iterate and repeat
```

### Testing Workflow

```bash
# 1. Build for testing environment
npm run build:android:test

# 2. Build test APK
npm run build:android:test -- --apk

# 3. Install and test on device
adb install android/app/build/outputs/apk/debug/app-debug.apk
```

### Production Workflow

```bash
# 1. Build for production environment
npm run build:android:prod

# 2. Build release AAB for Play Store
npm run build:android:prod -- --aab

# 3. Sign and upload to Play Console
```

## Performance Optimization

### Build Time Optimization

- **Incremental Builds**: Gradle caches build artifacts
- **Parallel Execution**: Multiple build steps run in parallel
- **Resource Optimization**: Assets are optimized for Android

### Memory Management

- **Gradle Daemon**: Reuses JVM for faster builds
- **Build Cache**: Caches compiled resources
- **Clean Builds**: Full cleanup when needed

## Troubleshooting

### Common Build Issues

#### Gradle Build Failures

```bash
# Clean Gradle cache
cd android && ./gradlew clean && cd ..

# Check Java version
java -version

# Verify Android SDK
echo $ANDROID_HOME
```

#### Capacitor Sync Issues

```bash
# Force full sync
npx cap sync android --force

# Check Capacitor configuration
cat capacitor.config.json
```

#### Asset Generation Issues

```bash
# Regenerate assets
npx capacitor-assets generate --android --force

# Check asset source files
ls -la src/assets/
```

### Debug Mode

```bash
# Enable verbose logging
./scripts/build-android.sh --verbose

# Show environment variables
./scripts/build-android.sh --env
```

## Best Practices

### Build Optimization

1. **Use Appropriate Environment**: Always specify the correct environment
2. **Clean When Needed**: Use `--clean` for troubleshooting
3. **Incremental Builds**: Avoid unnecessary full rebuilds
4. **Asset Management**: Keep assets optimized for mobile

### Development Workflow

1. **Development Builds**: Use `--dev` for daily development
2. **Testing Builds**: Use `--test` for QA testing
3. **Production Builds**: Use `--prod` for release builds
4. **Studio Integration**: Use `--studio` for debugging

### Error Prevention

1. **Resource Validation**: Always run resource checks
2. **Environment Consistency**: Use consistent environment variables
3. **Build Verification**: Test builds on actual devices
4. **Version Control**: Keep build scripts in version control

## Migration from Legacy System

### Backward Compatibility

The new system maintains full backward compatibility:

```bash
# Old command still works (now an alias)
npm run build:capacitor:android

# New commands provide more flexibility
npm run build:android:dev
npm run build:android:test
npm run build:android:prod
```

**Note:** All Android builds should use the `build:android*` pattern. The `build:capacitor:android*` scripts are provided as aliases for compatibility but will be deprecated in the future.

### Migration Checklist

- [ ] Update CI/CD pipelines to use new commands
- [ ] Update documentation references
- [ ] Train team on new build options
- [ ] Test all build environments
- [ ] Verify artifact locations

## Future Enhancements

### Planned Features

1. **Build Profiles**: Custom build configurations
2. **Automated Testing**: Integration with test suites
3. **Build Analytics**: Performance metrics and reporting
4. **Cloud Builds**: Remote build capabilities

### Integration Opportunities

1. **Fastlane Integration**: Automated deployment
2. **CI/CD Enhancement**: Pipeline optimization
3. **Monitoring**: Build performance tracking
4. **Documentation**: Auto-generated build reports

---

**Status**: Complete and ready for production use
**Last Updated**: 2025-07-11
**Version**: 1.0
**Maintainer**: Matthew Raymer