timesafari

6.7 KiB

Raw Blame History

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 ✅

Create config/assets/ directory structure
Create asset configuration schema (schema.json)
Create enhanced capacitor-assets configuration
Convert capacitor.config.json to capacitor.config.ts
Pin Node.js version (.nvmrc, .node-version)
Create dev-time asset configuration generator
Create asset configuration validator
Add npm scripts for asset management
Update .gitignore with proper asset exclusions
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

# 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

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

Rollback Plan

If issues arise during migration:

Restore backup branch: git checkout backup-before-asset-migration
Revert configuration changes: Remove new config files
Restore manual scripts: Re-enable previous asset generation
Investigate issues: Identify and resolve root causes
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