# 💾 Dotlaa ERP — Backup & Recovery Guide

This guide details the procedures for backing up, restoring, verifying, and recovering the Dotlaa ERP system in a production or staging environment.

---

## 1. Backup Configuration Verification

The backup system is powered by `spatie/laravel-backup`.
- **Configuration Path:** [config/backup.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/config/backup.php)
- **Schedule Configuration:** [console.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/routes/console.php#L11-L12)
  - Daily database backup at **01:00 AM**: `backup:run --only-db`
  - Daily backup cleanup at **02:00 AM**: `backup:clean`

To manually trigger a backup at any time:
```bash
php artisan backup:run --only-db
```
The resulting ZIP file containing the database dump is stored on the default configured disk (e.g. `storage/app/laravel-backup` for the `local` disk).

---

## 2. Database Restore Procedure

### A. Production (MySQL) Restore
Follow these steps to restore a MySQL database from a backup ZIP file:

1. **Locate and Extract the Backup:**
   Find the latest backup ZIP file in the storage directory or remote storage bucket. Extract it to retrieve the `.sql` dump file:
   ```bash
   unzip <backup-file>.zip -d /tmp/extracted-backup/
   ```
2. **Maintenance Mode:**
   Put the application into maintenance mode to prevent incoming writes during restoration:
   ```bash
   php artisan down --secret="pilot-restore-bypass"
   ```
3. **Restore the Database Dump:**
   Import the `.sql` file using the MySQL CLI tool:
   ```bash
   mysql -u [username] -p[password] -h [db_host] [database_name] < /tmp/extracted-backup/db-dumps/mysql-db.sql
   ```
4. **Clear Caches & Pre-requisites:**
   ```bash
   php artisan cache:clear
   php artisan route:clear
   php artisan config:clear
   ```
5. **Bring Application Back Up:**
   ```bash
   php artisan up
   ```

### B. Local / Staging (SQLite) Restore
If the environment is running SQLite:

1. **Locate SQLite File:**
   By default, the SQLite database is located at `database/database.sqlite`.
2. **Extract Database Backup:**
   Extract the `.sqlite` file from the backup ZIP:
   ```bash
   unzip <backup-file>.zip -d /tmp/extracted-sqlite/
   ```
3. **Overwrite database file:**
   Move the extracted sqlite file back to its correct location:
   ```bash
   cp /tmp/extracted-sqlite/database/database.sqlite database/database.sqlite
   ```

---

## 3. Full Application Restore Procedure

In the event of complete server loss:

1. **Re-clone Codebase:**
   ```bash
   git clone git@github.com:dotlaa/dotlaa_pos_backend.git /var/www/dotlaa_pos_backend
   cd /var/www/dotlaa_pos_backend
   ```
2. **Environment File Configuration:**
   Restore the `.env` file from your vault or create it from `.env.example`:
   ```bash
   cp .env.example .env
   nano .env
   ```
3. **Install Dependencies:**
   ```bash
   composer install --no-dev --optimize-autoloader
   npm install
   npm run build
   ```
4. **Restore Database:**
   Follow the **Database Restore Procedure** listed in Section 2.
5. **Storage Symlinks & Permissions:**
   Ensure public storage files and uploads directory permissions are locked down:
   ```bash
   php artisan storage:link
   chmod -R 775 storage bootstrap/cache
   chown -R www-data:www-data storage bootstrap/cache
   ```

---

## 4. Disaster Recovery Procedure (DRP)

In case of a catastrophic database corruption or ransomware attack:

| Step | Action | Command/Details |
|------|--------|-----------------|
| **1** | Terminate all active POS client connections | Revoke Sanctum access tokens if necessary, or put Nginx behind a static 503 page |
| **2** | Spin up a fresh database server (if hardware failed) | Provision MySQL node |
| **3** | Fetch the latest healthy backup | Retrieve the most recent ZIP file from S3 / external backups server |
| **4** | Restore the database | Use the standard database restore procedure above |
| **5** | Run migrations | Ensure any migrations added since the backup run are applied: `php artisan migrate` |
| **6** | Verify data integrity | Execute sanity SQL checks on sales counts, cashier shift statuses, and inventory totals |
| **7** | Re-route POS terminals | Direct traffic back to the primary app server and run `php artisan up` |

---

## 5. Backup Verification & Health Checks

To ensure that backups are healthy and restorable:

1. **Check Backup Monitor Status:**
   Run the monitor command to verify if backups are within maximum age and storage quotas:
   ```bash
   php artisan backup:monitor
   ```
2. **List Existing Backups:**
   ```bash
   php artisan backup:list
   ```
3. **Simulated Restoration Drill (Recommended Monthly):**
   - Download the latest backup.
   - Restore it to a local staging database clone.
   - Run automated tests or check basic endpoints (`GET /api/v1/products`, `GET /api/v1/sales`) to guarantee the database schema is readable and uncorrupted.