# Android Asset Validation System

**Author**: Matthew Raymer  
**Date**: 2025-08-22  
**Status**: 🎯 **ACTIVE** - Production Ready

## Overview

The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons.

## Problem Solved

Previously, Android builds would fail with errors like:
```
error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found.
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found.
```

This happened when:
- Source assets existed but weren't generated into Android resources
- Android resource directories were missing
- Asset generation tools weren't run before building

## Solution

### Enhanced Build Script Validation

The `scripts/build-android.sh` script now includes comprehensive asset validation that:

1. **Checks Source Assets**: Validates that required source files exist in `resources/`
2. **Checks Android Resources**: Verifies that generated Android resources exist
3. **Auto-Regenerates**: Automatically regenerates missing resources when detected
4. **Verifies Results**: Confirms that regeneration was successful

### Validation Process

```bash
# Validates and regenerates if needed
npm run assets:validate:android

# Full build with validation
npm run build:android:studio
```

### What Gets Validated

#### Source Assets (Required)
- `resources/icon.png` - App icon source
- `resources/splash.png` - Splash screen source  
- `resources/splash_dark.png` - Dark mode splash source

#### Android Resources (Generated)
- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable
- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities
- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities

### Density Levels Checked
- `mipmap-mdpi` (1x)
- `mipmap-hdpi` (1.5x)  
- `mipmap-xhdpi` (2x)
- `mipmap-xxhdpi` (3x)
- `mipmap-xxxhdpi` (4x)

## Usage

### Automatic Validation (Recommended)
The validation runs automatically during all Android builds:

```bash
# Development build with validation
npm run build:android:studio

# Production build with validation  
npm run build:android:prod

# Debug build with validation
npm run build:android:debug
```

### Manual Validation
Run validation only to check/fix assets:

```bash
# Validate and regenerate if needed
npm run assets:validate:android

# Alternative command
./scripts/build-android.sh --assets-only
```

### Validation Only (No Regeneration)
Check configuration without fixing:

```bash
npm run assets:validate
```

## Error Handling

### Missing Source Assets
If source assets are missing, the build fails with clear error messages:

```
[ERROR] Missing source assets:
[ERROR]   - resources/icon.png
[ERROR]   - resources/splash.png
[ERROR] Please ensure all required assets are present in the resources/ directory.
```

### Missing Generated Resources
If generated resources are missing, they're automatically regenerated:

```
[WARN] Missing Android resources detected:
[WARN]   - drawable/splash.png
[WARN]   - mipmap-mdpi/ic_launcher.png
[INFO] Regenerating Android assets...
[SUCCESS] Android assets regenerated successfully
```

### Generation Failure
If regeneration fails, helpful guidance is provided:

```
[ERROR] Failed to generate Android assets
[INFO] You may need to manually create the missing resources:
[INFO]   - android/app/src/main/res/drawable/splash.png
[INFO]   - android/app/src/main/res/mipmap-mdpi/ic_launcher.png
```

## Integration Points

### Build Script Integration
The validation is integrated into the main build process:

```bash
# In scripts/build-android.sh
validate_dependencies
validate_android_assets || {
    log_error "Android asset validation failed. Please fix the issues above and try again."
    exit 9
}
```

### NPM Scripts
New npm scripts for asset management:

```json
{
  "assets:validate": "npx tsx scripts/assets-validator.ts",
  "assets:validate:android": "./scripts/build-android.sh --assets-only",
  "assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true"
}
```

## Benefits

### For Developers
- **No More Build Failures**: Automatic detection and fixing of missing resources
- **Faster Development**: No need to manually run asset generation tools
- **Clear Error Messages**: Helpful guidance when issues occur
- **Consistent Results**: Same validation on all development machines

### For CI/CD
- **Reliable Builds**: Consistent asset validation across environments
- **Early Detection**: Catches issues before they reach production
- **Automated Fixes**: Self-healing builds when possible

### For Project Maintenance
- **Reduced Support**: Fewer "build doesn't work" issues
- **Documentation**: Clear requirements for required assets
- **Standardization**: Consistent asset structure across the project

## Troubleshooting

### Common Issues

#### "No assets found in the asset path"
This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them.

#### "Failed to generate Android assets"
Check that:
- Source assets exist in `resources/`
- `@capacitor/assets` is installed
- You have write permissions to the Android directories

#### "Asset generation completed but some resources are still missing"
This indicates a problem with the asset generation tool. Try:
1. Running `npm install` to ensure dependencies are up to date
2. Manually running `npx @capacitor/assets generate`
3. Checking the asset generation logs for specific errors

### Manual Recovery
If automatic regeneration fails, you can manually create the missing resources:

```bash
# Create missing directories
mkdir -p android/app/src/main/res/drawable
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}

# Copy source assets to assets directory
cp resources/icon.png assets/
cp resources/splash.png assets/
cp resources/splash_dark.png assets/

# Generate assets manually
npx @capacitor/assets generate

# Clean up
rm assets/icon.png assets/splash.png assets/splash_dark.png
```

## Future Enhancements

### Planned Improvements
- **iOS Asset Validation**: Extend validation to iOS assets
- **Asset Quality Checks**: Validate image dimensions and formats
- **Performance Optimization**: Cache validation results
- **CI/CD Integration**: Add validation to GitHub Actions

### Configuration Options
- **Custom Asset Paths**: Support for different asset directory structures
- **Validation Rules**: Configurable validation requirements
- **Skip Options**: Ability to skip validation for specific scenarios

## References

- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets)
- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources)
- [Build Script Documentation](./build-android.sh)
- [Asset Configuration](./capacitor-assets.config.json)

---

**Status**: Active validation system  
**Priority**: High  
**Maintainer**: Development team  
**Next Review**: 2025-09-22