# 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`.