# TimeSafari Asset Configuration Migration Plan

**Author**: Matthew Raymer  
**Date**: 2025-08-14  
**Status**: 🎯 **IMPLEMENTATION** - Ready for Execution

## Overview

This document outlines the migration from the current mixed asset management
system to a standardized, single-source asset configuration approach using
`capacitor-assets` as the standard generator.

## Current State Analysis

### Asset Sources (Duplicated)

- **`assets/` directory**: Contains `icon.png`, `splash.png`, `splash_dark.png`
- **`resources/` directory**: Contains identical files in platform-specific subdirectories
- **Result**: Duplicate storage, confusion about source of truth

### Asset Generation (Manual)

- **Custom scripts**: `generate-icons.sh`, `generate-ios-assets.sh`, `generate-android-icons.sh`
- **Bypass capacitor-assets**: Manual ImageMagick-based generation
- **Inconsistent outputs**: Different generation methods for each platform

### Configuration (Scattered)

- **`capacitor-assets.config.json`**: Basic configuration at root
- **Platform-specific configs**: Mixed in various build scripts
- **No validation**: No schema or consistency checks

## Target State

### Single Source of Truth

- **`resources/` directory**: Capacitor default location for source assets
- **Eliminate duplication**: Remove `assets/` directory after migration
- **Standardized paths**: All tools read from `resources/`

### Standardized Generation

- **`capacitor-assets`**: Single tool for all platform asset generation
- **Build-time generation**: Assets generated during build, not committed
- **Deterministic outputs**: Same inputs → same outputs every time

### Centralized Configuration

- **`config/assets/`**: All asset-related configuration files
- **Schema validation**: JSON schema for configuration validation
- **CI safeguards**: Automated validation and compliance checks

## Migration Steps

### Phase 1: Foundation Setup ✅

- [x] Create `config/assets/` directory structure
- [x] Create asset configuration schema (`schema.json`)
- [x] Create enhanced capacitor-assets configuration
- [x] Convert `capacitor.config.json` to `capacitor.config.ts`
- [x] Pin Node.js version (`.nvmrc`, `.node-version`)
- [x] Create dev-time asset configuration generator
- [x] Create asset configuration validator
- [x] Add npm scripts for asset management
- [x] Update `.gitignore` with proper asset exclusions
- [x] Create CI workflow for asset validation

### Phase 2: Validation & Testing

- [ ] Run `npm run assets:config` to generate new configuration
- [ ] Run `npm run assets:validate` to verify configuration
- [ ] Test `npm run build:native` workflow
- [ ] Verify CI workflow passes all checks
- [ ] Confirm no platform assets are committed to VCS

### Phase 3: Cleanup & Removal

- [ ] Remove `assets/` directory (after validation)
- [ ] Remove manual asset generation scripts
- [ ] Remove asset checking scripts
- [ ] Update documentation references
- [ ] Final validation of clean state

## Implementation Details

### File Structure

```
resources/                     # Image sources ONLY
  icon.png
  splash.png
  splash_dark.png

config/assets/                 # Versioned config & schema
  capacitor-assets.config.json
  schema.json

scripts/
  assets-config.js            # Dev-time config generator
  assets-validator.js         # Schema validator
```

### Configuration Schema

The schema enforces:
- Source files must be in `resources/` directory
- Required fields for icon and splash sections
- Android adaptive icon support (foreground/background/monochrome)
- iOS LaunchScreen preferences
- Target directory validation

### CI Safeguards

- **Schema validation**: Configuration must comply with schema
- **Source file validation**: All referenced files must exist
- **Platform asset denial**: Reject commits with generated assets
- **Clean tree enforcement**: Build must not modify committed configs

## Testing Strategy

### Local Validation

```bash
# Generate configuration
npm run assets:config

# Validate configuration
npm run assets:validate

# Test build workflow
npm run build:native

# Clean generated assets
npm run assets:clean
```

### CI Validation

- **Asset validation workflow**: Runs on asset-related changes
- **Schema compliance**: Ensures configuration follows schema
- **Source file existence**: Verifies all referenced files exist
- **Platform asset detection**: Prevents committed generated assets
- **Build tree verification**: Ensures clean tree after build

## Risk Mitigation

### Data Loss Prevention

- **Backup branch**: Create backup before removing `assets/`
- **Validation checks**: Multiple validation steps before removal
- **Gradual migration**: Phase-by-phase approach with rollback capability

### Build Continuity

- **Per-platform scripts unchanged**: All existing build orchestration preserved
- **Standard toolchain**: Uses capacitor-assets, not custom scripts
- **Fallback support**: Manual scripts remain until migration complete

### Configuration Consistency

- **Schema enforcement**: JSON schema prevents invalid configurations
- **CI validation**: Automated checks catch configuration issues
- **Documentation updates**: Clear guidance for future changes

## Success Criteria

### Technical Requirements

- [ ] Single source of truth in `resources/` directory
- [ ] All platform assets generated via `capacitor-assets`
- [ ] No manual asset generation scripts
- [ ] Configuration validation passes all checks
- [ ] CI workflow enforces asset policies

### Quality Metrics

- [ ] Zero duplicate asset sources
- [ ] 100% configuration schema compliance
- [ ] No platform assets committed to VCS
- [ ] Clean build tree after asset generation
- [ ] Deterministic asset outputs

### User Experience

- [ ] Clear asset management documentation
- [ ] Simple development commands
- [ ] Consistent asset generation across platforms
- [ ] Reduced confusion about asset sources

## Next Steps

1. **Execute Phase 2**: Run validation and testing steps
2. **Verify CI workflow**: Ensure all checks pass
3. **Execute Phase 3**: Remove duplicate assets and scripts
4. **Update documentation**: Finalize README and BUILDING.md
5. **Team training**: Ensure all developers understand new workflow

## Rollback Plan

If issues arise during migration:

1. **Restore backup branch**: `git checkout backup-before-asset-migration`
2. **Revert configuration changes**: Remove new config files
3. **Restore manual scripts**: Re-enable previous asset generation
4. **Investigate issues**: Identify and resolve root causes
5. **Plan revised migration**: Adjust approach based on lessons learned

---

**Status**: Ready for Phase 2 execution  
**Priority**: High  
**Estimated Effort**: 2-3 hours  
**Dependencies**: CI workflow validation  
**Stakeholders**: Development team