Cron Jobs Summary

This document lists all cron jobs that should be configured for the HiveJournal application.

Current Cron Endpoints

1. Workout Window - Daily Chain Generation

Endpoint: POST /api/workout-window/cron/generate-chains
Schedule: Daily at midnight UTC (0 0 * * *)
Secret: WORKOUT_WINDOW_CRON_SECRET
Purpose: Generates daily workout chains for matching users
Documentation: docs/WORKOUT_WINDOW_CRON_SETUP.md

2. Workout Window - Weekly Battle Generation

Endpoint: POST /api/workout-window/battle/cron/generate-weekly
Schedule: Weekly on Monday at midnight UTC (0 0 * * 1)
Secret: WORKOUT_WINDOW_CRON_SECRET
Purpose: Generates weekly team battles
Documentation: docs/WORKOUT_WINDOW_CRON_SETUP.md

3. Chat - Note Analysis

Endpoint: POST /api/chat/cron/analyze-notes
Schedule: Daily at 2 AM UTC (0 2 * * *)
Secret: CHAT_CRON_SECRET or WORKOUT_WINDOW_CRON_SECRET
Purpose: Analyzes journal entries for users with read_notes_enabled: true
Documentation: docs/CHAT_NOTE_ANALYSIS_CRON.md

4. Encouragement Drops - Daily JQ Drops

Endpoint: POST /api/encouragement-drops/cron/generate-daily-drops
Schedule: Daily at 9 AM UTC (0 9 * * *)
Secret: DROPS_CRON_SECRET, WORKOUT_WINDOW_CRON_SECRET, or CHAT_CRON_SECRET
Purpose: Generates personalized daily drops from JQ for users with check-ins enabled
Documentation: docs/JQ_DAILY_DROPS_CRON.md
Note: Should run AFTER note analysis (2 AM) to use fresh analysis data

5. Encouragement Drops - Engagement Processing

Endpoint: POST /api/encouragement-drops/cron/process-engagement
Schedule: Hourly (0 * * * *)
Secret: DROPS_CRON_SECRET, WORKOUT_WINDOW_CRON_SECRET, or CHAT_CRON_SECRET
Purpose: Checks if recipients increased engagement after receiving drops and awards bonus drops
Documentation: docs/ENCOURAGEMENT_DROPS.md

6. Drops - Monthly Award

Endpoint: POST /api/drops/cron/award-monthly-all
Schedule: Monthly on the 1st at midnight UTC (0 0 1 * *)
Secret: DROPS_CRON_SECRET (optional)
Purpose: Awards monthly drops to all users
Documentation: docs/ENCOURAGEMENT_DROPS.md

7. Spotify - Sync All

Endpoint: POST /api/spotify/sync-all
Schedule: Every 15 minutes (*/15 * * * *) or hourly (0 * * * *)
Secret: SPOTIFY_SYNC_CRON_SECRET
Purpose: Syncs listening history for all connected Spotify accounts
Documentation: docs/SPOTIFY_SETUP.md

8. DreamPro - Process Step Prompts

Endpoint: POST /api/dreampro/cron/process-step-prompts
Schedule: Daily at 3 AM UTC (0 3 * * *)
Secret: DREAMPRO_CRON_SECRET or WORKOUT_WINDOW_CRON_SECRET
Purpose: Processes step prompts for users who haven't been prompted in 3+ days
Documentation: docs/DREAMPRO_COMPLETE.md

Recommended Schedule Summary

Vercel Cron Configuration

If using Vercel, add to apps/frontend/vercel.json:

{
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm install",
  "framework": "nextjs",
  "outputDirectory": ".next",
  "crons": [
    {
      "path": "/api/workout-window/cron/generate-chains",
      "schedule": "0 0 * * *"
    },
    {
      "path": "/api/workout-window/battle/cron/generate-weekly",
      "schedule": "0 0 * * 1"
    },
    {
      "path": "/api/chat/cron/analyze-notes",
      "schedule": "0 2 * * *"
    },
    {
      "path": "/api/encouragement-drops/cron/generate-daily-drops",
      "schedule": "0 9 * * *"
    },
    {
      "path": "/api/encouragement-drops/cron/process-engagement",
      "schedule": "0 * * * *"
    },
    {
      "path": "/api/drops/cron/award-monthly-all",
      "schedule": "0 0 1 * *"
    },
    {
      "path": "/api/dreampro/cron/process-step-prompts",
      "schedule": "0 3 * * *"
    }
  ]
}

Note: Vercel cron jobs run on the frontend. You'll need to create API routes that proxy to your backend, or use external cron services for backend endpoints.

Railway Cron Configuration

Railway doesn't have built-in cron support. Use external cron services or Railway's scheduled tasks feature.

External Cron Service Setup

For backend endpoints, use external cron services like:

• cron-job.org
• EasyCron
• Cronitor

Required Headers

All cron endpoints require the x-cron-secret header:

x-cron-secret: your-secret-token-here

Environment Variables

Set these in your backend .env:

WORKOUT_WINDOW_CRON_SECRET=your-secret-token-here
CHAT_CRON_SECRET=your-secret-token-here
DROPS_CRON_SECRET=your-secret-token-here
SPOTIFY_SYNC_CRON_SECRET=your-secret-token-here
DREAMPRO_CRON_SECRET=your-secret-token-here

You can use the same secret for multiple jobs if preferred.

Testing Cron Jobs

Test each endpoint manually:

# Workout Window Chains
curl -X POST https://your-backend-url.com/api/workout-window/cron/generate-chains \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# Note Analysis
curl -X POST https://your-backend-url.com/api/chat/cron/analyze-notes \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# JQ Daily Drops
curl -X POST https://your-backend-url.com/api/encouragement-drops/cron/generate-daily-drops \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# Engagement Processing
curl -X POST https://your-backend-url.com/api/encouragement-drops/cron/process-engagement \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# Monthly Drops
curl -X POST https://your-backend-url.com/api/drops/cron/award-monthly-all \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# Spotify Sync
curl -X POST https://your-backend-url.com/api/spotify/sync-all \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# DreamPro Step Prompts
curl -X POST https://your-backend-url.com/api/dreampro/cron/process-step-prompts \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

# Weekly Battles
curl -X POST https://your-backend-url.com/api/workout-window/battle/cron/generate-weekly \
  -H "x-cron-secret: your-secret-token" \
  -H "Content-Type: application/json"

Monitoring

Monitor cron jobs to ensure:

• All jobs run on schedule
• No errors occur
• Jobs complete successfully

Check backend logs for:

• Job start messages
• Success/failure counts
• Error messages
• Processing times

Priority Order

If you need to set up cron jobs incrementally, prioritize:

1. High Priority:

   • Note Analysis (2 AM) - Required for JQ features
   • JQ Daily Drops (9 AM) - User-facing feature
   • Workout Window Chains (midnight) - Core feature

2. Medium Priority:

   • Engagement Processing (hourly) - Bonus drops
   • DreamPro Step Prompts (3 AM) - Feature enhancement
   • Weekly Battles (Monday) - Feature enhancement

3. Low Priority:

   • Monthly Drops (1st of month) - Periodic reward
   • Spotify Sync (every 15 min) - Background sync