NutriKit Supabase Backup System Documentation

An automated daily backup system that exports all NutriKit Supabase database tables to GitHub, providing disaster recovery and data protection for production user data.

                                    DAILY CRON (3 AM UTC)
                                           |
                                           v
+------------------+              +-------------------+
|                  |              |                   |
|  Vercel Cron     |------------->|  /api/backup      |
|  (vercel.json)   |   trigger    |  (Next.js API)    |
|                  |              |                   |
+------------------+              +-------------------+
                                           |
                           +---------------+---------------+
                           |                               |
                           v                               v
                  +------------------+            +------------------+
                  |                  |            |                  |
                  |  Supabase        |            |  GitHub API      |
                  |  (Data Source)   |            |  (Storage)       |
                  |                  |            |                  |
                  +------------------+            +------------------+
                           |                               |
                           |                               v
                           |                     +------------------+
                           |                     |  nutrikit-       |
                           +-------------------->|  backups repo    |
                              fetch all tables   |  (public)        |
                              with pagination    +------------------+
                                                          |
                                                          v
                                                 backups/
                                                 └── 2026-01-02/
                                                     ├── users.json.gz
                                                     ├── foods.json.gz
                                                     ├── preferences.json.gz
                                                     ├── days.json.gz
                                                     ├── meals.json.gz
                                                     ├── meal_items.json.gz
                                                     ├── user_foods.json.gz
                                                     └── meal_presets.json.gz

1. Vercel Cron Job

File: vercel.json

{
  "crons": [
    {
      "path": "/api/backup",
      "schedule": "0 3 * * *"
    }
  ]
}

• ●Schedule: Daily at 3:00 AM UTC
• ●Endpoint: /api/backup
• ●Authentication: Uses CRON_SECRET environment variable

2. Backup API Endpoint

File: app/api/backup/route.ts

Responsibilities:

• ●Authenticates requests using Bearer token
• ●Connects to Supabase using service role key (bypasses RLS)
• ●Fetches all rows from each table with pagination (1000 rows per request)
• ●Filters out sensitive fields from user data
• ●Compresses data with gzip
• ●Uploads each table as a separate file to GitHub
• ●Triggers cleanup of old backups

3. GitHub Repository

Repository: https://github.com/pxlshpr/nutrikit-backups

Structure:

nutrikit-backups/
└── backups/
    ├── .gitkeep
    ├── 2026-01-02/
    │   ├── users.json.gz
    │   ├── foods.json.gz
    │   ├── preferences.json.gz
    │   ├── days.json.gz
    │   ├── meals.json.gz
    │   ├── meal_items.json.gz
    │   ├── user_foods.json.gz
    │   └── meal_presets.json.gz
    └── 2026-01-03/
        └── ...

Backup Process

1. Vercel Cron triggers /api/backup at 3 AM UTC
                    |
                    v
2. API validates CRON_SECRET in Authorization header
                    |
                    v
3. For each table (users, foods, preferences, days, meals, meal_items, user_foods, meal_presets):
   |
   +---> a. Fetch all rows with pagination (1000 per request)
   |
   +---> b. Filter sensitive fields (apple_user_id, cloudkit_id, device_ids)
   |
   +---> c. JSON stringify the data
   |
   +---> d. Compress with gzip
   |
   +---> e. Base64 encode for GitHub API
   |
   +---> f. Upload to GitHub: backups/{date}/{table}.json.gz
                    |
                    v
4. Cleanup old backups based on retention policy
                    |
                    v
5. Return success response with row counts and file sizes

Retention Policy

+------------------+-------------------+------------------+
|   Age Range      |   Retention       |   Example        |
+------------------+-------------------+------------------+
|   0-30 days      |   Keep ALL        |   30 backups     |
|   30-90 days     |   Keep 1/week     |   ~8 backups     |
|   90+ days       |   Keep 1/month    |   ~12/year       |
+------------------+-------------------+------------------+

Estimated annual storage: ~50 backup sets x 4.5 MB = ~225 MB
Well under GitHub's 1 GB soft limit

Total compressed size: ~4.5 MB per backup

Sensitive Data Handling

The following fields are excluded from backups:

• ●users.apple_user_id - Apple Sign-In identifier
• ●users.cloudkit_id - CloudKit user identifier
• ●users.device_ids - User's device identifiers

Authentication

Environment Variables

Download a Backup

# Clone the repo
git clone https://github.com/pxlshpr/nutrikit-backups.git
cd nutrikit-backups

# Decompress a specific table
gunzip -k backups/2026-01-02/foods.json.gz

# View the data
cat backups/2026-01-02/foods.json | jq '.[0]'

Restore to Supabase

# Using Supabase CLI or direct SQL
# Example: Restore foods table
cat foods.json | jq -c '.[]' | while read row; do
  # Insert each row via Supabase API or psql
done

curl -H "Authorization: Bearer YOUR_CRON_SECRET" \
  https://nutri-kit.vercel.app/api/backup

Response:

{
  "success": true,
  "timestamp": "2026-01-02",
  "tables": [
    {"table": "users", "rows": 74, "size": 2932},
    {"table": "foods", "rows": 7006, "size": 2511670},
    ...
  ]
}

Success Indicators

• ●Daily commits to nutrikit-backups repo
• ●Each commit contains 8 .json.gz files
• ●Response includes row counts matching production data

Failure Indicators

• ●No new commits for 24+ hours
• ●API returns 500 error
• ●Missing tables in backup folder

Vercel Logs

View function logs at: https://vercel.com/ahmed-khalafs-projects-75b160b9/nutrikit/logs

Total: $0/month

nutrikit-website repository

1. ●app/api/backup/route.ts - Backup API endpoint
2. ●vercel.json - Cron job configuration
3. ●package.json - Added @supabase/supabase-js and @octokit/rest

New Repository

• ●pxlshpr/nutrikit-backups - Public repo storing all backups

• ● Email notification on backup failure
• ● Webhook to Slack/Discord on completion
• ● Backup verification (checksum validation)
• ● Point-in-time recovery documentation
• ● Automated restore testing