# 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 and constants
    backup.service.ts     # Core backup operations
    backup-archive.service.ts      # Archive creation
    backup-restore.service.ts      # Restore operations
    backup-retention.service.ts    # Tiered retention enforcement
    backup-classification.service.ts  # Backup category classification
  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
    002_add_retention_categories.sql  # Tiered retention columns
  tests/                  # Test files
    unit/
      backup-classification.service.test.ts  # Classification tests
```

## 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 (tiered):**
- Runs immediately after each successful scheduled backup
- Uses tiered classification: each backup can belong to multiple categories
- A backup is only deleted when it exceeds ALL applicable category quotas
- Also runs globally at 4 AM daily as a safety net

## Tiered Retention System

Backups are classified by their creation timestamp into categories:

| Category | Qualification | Retention Count |
|----------|--------------|-----------------|
| hourly | All backups | 8 |
| daily | First backup at midnight UTC | 7 |
| weekly | First backup on Sunday at midnight UTC | 4 |
| monthly | First backup on 1st of month at midnight UTC | 12 |

**Multi-category classification:**
- A backup can belong to multiple categories simultaneously
- Example: Backup at midnight on Sunday, January 1st qualifies as: hourly + daily + weekly + monthly

**Retention logic:**
```
For each category (hourly, daily, weekly, monthly):
  1. Get all backups with this category
  2. Keep top N (sorted by started_at DESC)
  3. Add to protected set

A backup is deleted ONLY if it's NOT in the protected set
(i.e., exceeds quota for ALL its categories)
```

**Expiration calculation:**
- Each backup's `expires_at` is calculated based on its longest retention period
- Monthly backup: 12 months from creation
- Weekly-only backup: 4 weeks from creation
- Daily-only backup: 7 days from creation
- Hourly-only backup: 8 hours from creation

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