feat(backend): add automated database backup, restore, and rotation (#201)

[DaddyMord]

Verification Commands

npm test (backend) ✅ passed (155/155)
node --check backup.js / restore.js ✅ passed
backup CLI smoke test (create → verify → restore → rotate) ✅ passed
YAML workflow parse ✅ valid

Overview

This PR adds automated database backup, restore, and rotation to backend so the platform's persistent data can be recovered after a disaster. It backs up every data source the backend owns — the JSON data files (data.json, webhooks.json) and the SQL database (SQLite in dev/test, PostgreSQL in prod) — into verifiable, gzipped snapshots with a SHA-256 manifest, copies them offsite to S3, and enforces a retention policy. A documented restore path covers both local and offsite copies.

The core (create / verify / rotate / schedule) uses only Node built-ins. The AWS SDK, pg_dump, and better-sqlite3 are loaded lazily and only when configured, so no new runtime dependency is added (lockfile unchanged).

Related Issue

Closes #201

Changes

⚙️ Backup System

• [ADD] backend/backup.js
• Added the core backup engine: creates backups/backup-<timestamp>/ containing one gzipped member per source plus a manifest.json of SHA-256 checksums.
• Captures SQLite via the better-sqlite3 online-backup API and PostgreSQL via pg_dump; both are optional and lazily loaded.
• Implemented verification (verifyBackup) — every member must gunzip cleanly and match its manifest checksum.
• Implemented retention/rotation (selectExpired / rotateBackups) by age (BACKUP_RETENTION_DAYS) and count (BACKUP_RETENTION_MAX), applied locally and in S3.
• Added optional S3 offsite upload + remote rotation (supports S3-compatible stores via BACKUP_S3_ENDPOINT).
• Added an opt-in, dependency-free in-process scheduler (startBackupScheduler, gated by BACKUP_ENABLED).
• Added a CLI: --list, --verify-latest, and a full create → verify → upload → rotate run.

♻️ Restore

• [ADD] backend/restore.js
• Restores a backup locally or from S3 (--from-s3), verifying it first (overridable with --force).
• Moves any file it would overwrite to <file>.pre-restore, so every restore is reversible.
• Writes PostgreSQL dumps to disk and prints the manual psql restore command rather than overwriting a live DB automatically.

🌐 Scheduling (cron job)

• [ADD] .github/workflows/backup.yml
• Added a scheduled GitHub Actions workflow (daily at 03:00 UTC, plus manual workflow_dispatch) that creates a verified backup, uploads it to S3, and attaches it to the run as an additional copy.

🔧 Configuration & Wiring

• [MODIFY] backend/index.js — start the optional backup scheduler on boot (no-op unless BACKUP_ENABLED=true).
• [MODIFY] backend/package.json — added backup, backup:list, backup:verify, and restore scripts.
• [MODIFY] backend/.env.example — documented all backup/retention/S3 environment variables.
• [MODIFY] .gitignore — ignore *.db, backups/, restore-database.sql, *.pre-restore.

📚 Documentation

• [ADD] docs/backups.md — backup contents, scheduling options (CI / cron / in-process), S3 setup, retention, and the full restore + disaster-recovery runbook.
• [MODIFY] README.md — linked the new backup guide from the Documentation section.

🧪 Tests

• [ADD] backend/__tests__/backup.test.js
• Config defaults and S3 config parsing.
• Backup creation + verification round-trip, including tamper detection.
• Retention selection (age + count) and on-disk rotation.
• Restore round-trip (with .pre-restore preservation) and refusal of corrupt backups.

Verification Results

Acceptance Criteria	Status
Set up backup cron job	✅ GitHub Actions workflow + system-cron examples + in-process scheduler
Configure backup schedule (daily/weekly)	✅ daily CI cron + configurable interval
Store backups in cloud storage (S3)	✅ uploadBackupToS3 (+ S3-compatible endpoints)
Implement backup rotation	✅ age + count retention, local and S3
Add backup verification	✅ SHA-256 manifest + gzip integrity check
Document restore process	✅ docs/backups.md restore runbook
Backend test suite passes	✅ 155/155 (11 new)

[drips-wave]

@DaddyMord Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits