Backup Restoration

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/backup-restoration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants can restore their AstroBaaS instance from any historical backup (within retention window). Restore is atomic: either entire backup is applied or nothing is applied. After restore, merchants verify data is correct before switching traffic. Core owns the restore process and rollback safety; this is infrastructure, not a paid feature.

The problem

If data is corrupted or deleted, merchants have no way to recover. Restore from backup must be simple and safe, with no data loss between backup and recovery point.

What it does

• Restore selection: admin chooses which backup to restore
• Restore preview: before committing, admin can view backup metadata (timestamp, size, item counts)
• Atomic restore: entire backup is applied; no partial restores (to avoid inconsistency)
• Rollback safety: if restore is triggered by mistake, old data is preserved for manual recovery
• Restore verification: after restore, merchant can verify data is correct (order count, customer count, etc.)
• Downtime notification: admin receives email before/after restore with status
• Audit log: every restore action is logged (who, when, which backup, success/failure)

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.

• Point-in-time recovery: we restore entire backup, not individual records (granular PITR requires premium feature).
• Live restore: restore requires downtime (customers cannot access shop during restore); merchant must plan downtime.
• Selective restore: we do not restore products only, orders only, etc.; all data is restored together (consistency over granularity).

Data model

New document: restore_record { restoreId, backupId, initiatedAt, completedAt, status (pending, completed, failed), error_message, data_counts { products, customers, orders } }.

API

• GET /api/restore/backup-list -> list of available backups for restore
• POST /api/restore/preview { backupId } -> { backupId, timestamp, size, item_counts }
• POST /api/restore/start { backupId } -> { restoreId, estimatedDuration }
• GET /api/restore/{restoreId}/status -> { status, progress, error }
• POST /api/restore/{restoreId}/verify { data_counts } -> { verified, mismatches }
• POST /api/restore/cancel/{restoreId} (admin only, while still pending)

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: available backups for restore (sorted by date), restore preview (item counts, timestamp), restore status during operation, verification checklist (product count, customer count, order count).

The seam — why this is core

Core owns restore process, atomicity, and rollback safety. No paid seam; this is infrastructure.

Core owns the interface + honest restore tool; disaster recovery is infrastructure, not a credential or support commitment.

Dependencies

• backup subsystem (existing; provides backup files)
• database 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 selects backup from 2026-08-15; preview shows 1000 products, 500 customers, 2000 orders
• Admin clicks ‘Restore’; status shows ‘in progress’, ETA 5 minutes
• Restore completes; data is verified to have 1000 products, 500 customers, 2000 orders
• If restore fails mid-way (error), old data is preserved; no partial data left
• Admin receives email: ‘Restore started at 2026-09-03 10:00 UTC’ and ‘Restore completed at 10:05 UTC’
• Restore can be cancelled while pending; running restore cannot be cancelled (to avoid partial state)
• Audit log shows: Restore initiated by user@example.com, backup from 2026-08-15, completed successfully

Risks

If restore is not atomic, partial data leaves database inconsistent (orders without products, customers without emails). If old data is overwritten without preservation, merchant cannot recover from bad restore. If restore verification is manual and skipped, merchant doesn’t notice until customers complain. If restore process crashes, database is left in intermediate state and cannot be recovered. If data counts are wrong (off by 1 or 100), merchant doesn’t catch error during verify step.

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.