Legacy System Migration

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €399 one-time; support commitment: data ETL, cleanup, validation

Generated from docs/plan/paid/legacy-system-migration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants migrating from legacy systems (old Magento, custom PHP, flat file) can import their product catalog, customer database, and transaction history into AstroBaaS. The paid pack provides ETL engineering, data cleanup, and post-migration validation; core owns the generic import interface.

The problem

Merchants running legacy ecommerce systems face data quality issues, missing schema information, and risk of data loss during migration. A generic import tool with cleanup and validation reduces risk.

What it does

• Generic CSV/JSON import: merchants upload exported data in flexible format (column mapping required)
• Column mapping UI: admin maps source columns to AstroBaaS fields (name, email, amount, etc.)
• Data cleanup: trim whitespace, deduplicate emails, convert prices to integers (minor units)
• Type conversion: parse dates (multiple formats supported), currencies (user selects source currency), product IDs
• Validation: check for required fields, valid email format, numeric prices, non-null keys
• Batch import: handle 50K+ rows with progress bar and resumable uploads
• Rollback within 24 hours: undo entire import if issues discovered
• Audit trail: log every row imported, any transformations applied

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Custom ETL per merchant: we provide generic tools; merchants with unique schemas work with Paid Support (not included in this feature).
• Live sync during migration: import is one-time; live two-way sync requires per-system integration (separate feature: sync-legacy-erp or similar).
• Schema inference: merchants must provide column mapping; we do not auto-detect schema (error-prone).
• Historical data reconstruction: if legacy system has no audit trail, we cannot recreate it; merchants get the last state only.

Data model

import_template { templateId, name, columnMapping { source, destination, type, required }, createdBy, createdAt }. import_job { jobId, templateId, status, rowsProcessed, rowsSkipped, errors, startedAt, completedAt, rollbackDeadline }.

API

• POST /api/import/legacy/template { name, columnMapping } -> { templateId }
• GET /api/import/legacy/template (admin only) -> list of saved templates
• POST /api/import/legacy/start { templateId, csvFile OR jsonFile } -> { jobId, preview }
• GET /api/import/legacy/{jobId}/status -> { status, rowsProcessed, rowsSkipped, errors }
• POST /api/import/legacy/{jobId}/confirm -> { started }
• POST /api/import/legacy/{jobId}/rollback (within 24 hours)
• GET /api/import/legacy/{jobId}/report (admin only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: import template builder (define column mapping), file upload with preview (first 10 rows), progress bar, error log (row, field, error reason), rollback button, import history.

The seam — why this is paid

Core owns the generic import interface and ETL orchestration. Paid pack owns: data cleanup rules, type conversion logic, validation rules, ETL engineering support.

Support commitment: legacy data import, schema mapping, post-migration SLA

Dependencies

• product subsystem (existing)
• customer subsystem (existing)
• order subsystem (existing)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Admin defines template: map ‘product_name’ to ‘name’, ‘sku’ to ‘sku’, ‘stock_qty’ to ‘inventory’
• CSV with 10K products, 20K customers imports in under 10 minutes
• Prices in legacy format ‘100.50 EUR’ are converted to 10050 (minor units, integer)
• Validation detects 100 rows with missing customer email; admin chooses to skip these rows
• Duplicate customer emails are deduplicated (first occurrence wins, duplicates logged)
• After successful import, admin can rollback within 24 hours; imported products are removed
• Import report shows 10000 products imported, 100 skipped, 50 errors (by type)
• Audit trail logs: row 5, field ‘email’, error ‘invalid format’, action ‘skipped’

Risks

If column mapping is wrong (destination is swapped for two fields), data is imported to wrong columns and products are corrupted. If price conversion is lossy (rounding errors), merchants lose precision on 50K+ products. If deduplication keeps wrong duplicate (second instead of first), customers see wrong data. If rollback is not atomic, partial data remains. If validation is skipped, garbage data propagates.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.