Chat Note Analysis Cron Setup

This document explains how to set up the daily batch job that analyzes user notes and metadata for JQ chatbot recommendations.

Overview

The note analysis system:

Analyzes journal entries from users who have enabled "Let JQ Read Your Notes"
Identifies mood trends, topics, patterns, and insights
Generates personalized recommendations
Stores analysis results for JQ to reference during conversations

Endpoints

Cron Endpoint (Protected)

POST /api/chat/cron/analyze-notes

This endpoint is protected by a secret token and should be called by your cron service.

Headers:

x-cron-secret: Secret token (set via CHAT_CRON_SECRET env var, or falls back to WORKOUT_WINDOW_CRON_SECRET)

Response:

{
  "success": true,
  "message": "Analyzed notes for 15 users",
  "results": {
    "total": 15,
    "successful": 14,
    "failed": 1,
    "errors": ["User abc123: No entries found"]
  }
}

Environment Variables

Add to your backend .env file:

CHAT_CRON_SECRET=your-secret-token-here

Or use the existing WORKOUT_WINDOW_CRON_SECRET if you prefer a shared secret.

Cron Service Setup

Vercel Cron

If using Vercel, add to vercel.json:

{
  "crons": [
    {
      "path": "/api/chat/cron/analyze-notes",
      "schedule": "0 2 * * *"
    }
  ]
}

Railway Cron

If using Railway, you can use their cron job feature or set up an external cron service.

External Cron Service

You can use services like:

Configure them to make a POST request to:

https://your-backend-url.com/api/chat/cron/analyze-notes

With header:

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

Recommended Schedule

Daily at 2 AM UTC: Analyze notes from the previous day
This gives users time to complete their daily journaling before analysis

What Gets Analyzed

For each user with read_notes_enabled: true, the system:

Fetches recent entries: Last 7 days, up to 50 most recent entries
Analyzes with AI:
- Summary of journaling patterns
- Mood trends (most common moods, daily trends)
- Key topics and themes
- Behavioral patterns
- Recommendations
- Insights (gratitude, challenges, goals, achievements)
Stores results: Saved in note_analyses table with date

How JQ Uses the Analysis

When a user chats with JQ and has read_notes_enabled: true:

JQ receives the latest note analysis in its system prompt
JQ can reference:
- Specific patterns noticed
- Topics the user has been writing about
- Mood trends
- Recommendations generated from the analysis
- Gratitude themes, challenges, goals, and achievements
JQ provides highly personalized suggestions based on the analysis

Testing

You can test the cron endpoint manually:

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

Monitoring

Monitor the cron job to ensure:

Analyses are generated daily
No errors occur during processing
All eligible users are analyzed

Check your backend logs for:

[Note Analyzer] Starting analysis for X users
[Note Analyzer] Successfully analyzed notes for user...
[Note Analyzer] Completed: X successful, Y failed
Any error messages

Performance Considerations

The system processes users in batches of 5 to avoid overwhelming the API
There's a 1-second delay between batches to avoid rate limits
Only users with read_notes_enabled: true are analyzed
Analysis is skipped if a user has no recent entries

Database Schema

Analyses are stored in the note_analyses table:

user_id: User who owns the analysis
analysis_date: Date of the analysis (one per day per user)
summary: Overall summary of recent entries
mood_trends: JSONB with mood patterns
topics: JSONB array of key topics
patterns: JSONB array of behavioral patterns
recommendations: AI-generated recommendations
insights: JSONB with gratitude, challenges, goals, achievements
entry_count: Number of entries analyzed

Future Enhancements

Weekly/monthly summaries
Trend analysis over longer periods
Comparison with previous periods
Proactive check-ins based on analysis
Custom analysis prompts per user