motovaultpro/backend/src/features/backup/README.md

Backup Feature

Complete backup and restore system for MotoVaultPro.

Overview

This feature provides:

• Manual and scheduled backups of the PostgreSQL database and document files
• Multiple backup schedules with individual retention policies
• Restore functionality with safety backup creation
• Email notifications on backup success/failure

Architecture

backup/
  api/                    # HTTP endpoints
    backup.routes.ts      # Route definitions
    backup.controller.ts  # Request handlers
    backup.validation.ts  # Zod schemas
  domain/                 # Business logic
    backup.types.ts       # TypeScript types
    backup.service.ts     # Core backup operations
    backup-archive.service.ts    # Archive creation
    backup-restore.service.ts    # Restore operations
    backup-retention.service.ts  # Retention enforcement
  data/                   # Data access
    backup.repository.ts  # Database queries
  jobs/                   # Scheduled jobs
    backup-scheduled.job.ts  # Scheduled backup execution
    backup-cleanup.job.ts    # Retention cleanup
  migrations/             # Database schema
    001_create_backup_tables.sql

API Endpoints

All endpoints require admin authentication.

Backup Operations

Method	Path	Description
GET	/api/admin/backups	List backups with pagination
POST	/api/admin/backups	Create manual backup
GET	/api/admin/backups/:id	Get backup details
GET	/api/admin/backups/:id/download	Download backup file
DELETE	/api/admin/backups/:id	Delete backup
POST	/api/admin/backups/upload	Upload backup file

Restore Operations

Method	Path	Description
POST	/api/admin/backups/:id/restore/preview	Preview restore
POST	/api/admin/backups/:id/restore	Execute restore
GET	/api/admin/backups/restore/status	Get restore status

Schedule Operations

Method	Path	Description
GET	/api/admin/backups/schedules	List schedules
POST	/api/admin/backups/schedules	Create schedule
PUT	/api/admin/backups/schedules/:id	Update schedule
DELETE	/api/admin/backups/schedules/:id	Delete schedule
PATCH	/api/admin/backups/schedules/:id/toggle	Enable/disable

Settings

Method	Path	Description
GET	/api/admin/backups/settings	Get settings
PUT	/api/admin/backups/settings	Update settings

Backup Archive Format

Backups are .tar.gz archives containing:

motovaultpro_backup_YYYYMMDD_HHMMSS.tar.gz
  manifest.json           # Backup metadata
  database/
    motovaultpro.sql.gz   # Compressed PostgreSQL dump
  documents/
    <user_id>/            # User document files

Schedule Frequencies

Frequency	Cron	Default Time
hourly	0 * * * *	Every hour
daily	0 3 * * *	3:00 AM
weekly	0 3 * * 0	Sunday 3:00 AM
monthly	0 3 1 * *	1st of month 3:00 AM

Database Tables

• backup_schedules - Schedule configurations
• backup_history - Backup operation records
• backup_settings - Global settings

Storage

Backups are stored in /app/data/backups/ (mapped to ./data/backups/ on host).

Integration

Scheduler

Jobs are registered in backend/src/core/scheduler/index.ts:

• Backup check: Every minute
• Retention cleanup: Daily at 4 AM (also runs after each scheduled backup)

Distributed Locking

Scheduled backups use Redis distributed locking to prevent duplicate backups when multiple backend containers are running (blue-green deployments).

Lock behavior:

• Lock key: backup:schedule:{schedule_id}
• Lock TTL: 5 minutes (auto-release if container crashes)
• Only one container creates the backup; others skip

Retention cleanup:

• Runs immediately after each successful scheduled backup
• Deletes backups exceeding the schedule's retention count
• Also runs globally at 4 AM daily as a safety net

See backend/src/core/scheduler/README.md for the distributed locking pattern.

Admin Routes

Routes are registered in backend/src/features/admin/api/admin.routes.ts.