ChatRAG

Cloud Connectors (Nango)

Connect ChatRAG to your cloud storage providers and sync documents directly into your RAG knowledge base. Powered by Nango for secure OAuth integrations.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    User's Browser                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │   ChatRAG Documents Dashboard                       │   │
│  │   - Connect provider buttons                        │   │
│  │   - Folder/file pickers                             │   │
│  │   - Sync controls                                   │   │
│  └────────────────────────┬────────────────────────────┘   │
└───────────────────────────│─────────────────────────────────┘
                            │ OAuth via Nango
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      Nango Cloud                            │
│   - Secure token storage                                    │
│   - OAuth flow management                                   │
│   - API proxy & rate limiting                               │
└────────────────────────────┬────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│ Google Drive  │    │    Notion     │    │   Dropbox     │
└───────────────┘    └───────────────┘    └───────────────┘

Nango handles OAuth flows, token refresh, and API proxying - ChatRAG never stores your provider credentials.

Quick Start

Step 1: Get Nango API Key

  1. Sign up at app.nango.dev
  2. Go to Environment Settings → API Keys
  3. Copy your Secret Key

Step 2: Configure Environment

# Add to your .env.local
NEXT_PUBLIC_NANGO_ENABLED=true
NANGO_SECRET_KEY=your_secret_key_here
NANGO_WEBHOOK_SECRET=your_webhook_secret
NANGO_HOST=https://api.nango.dev

Step 3: Install Dependencies

npm install @nangohq/node @nangohq/frontend

Step 4: Connect a Provider

  1. Navigate to Documents dashboard in ChatRAG
  2. Click "Connect" on Google Drive, Notion, or Dropbox
  3. Complete OAuth flow in the popup
  4. Select folders/files to sync
  5. Click "Sync" to import documents

Provider Setup (Production)

For production, configure your own OAuth credentials for each provider. For development, Nango provides shared credentials.

Google Drive

1. Create Google Cloud Project

  • Go to console.cloud.google.com
  • Create new project named "ChatRAG"
  • Enable Google Drive API
  • Configure OAuth consent screen (External)
  • Create OAuth 2.0 credentials (Web application)

2. Set Redirect URI

https://api.nango.dev/oauth/callback

3. Configure in Nango Dashboard

Paste Client ID and Secret in Nango → Integrations → google-drive

Notion

1. Create Notion Integration

2. Enable OAuth

  • Go to Distribution tab
  • Enable OAuth 2.0
  • Add redirect URI: https://api.nango.dev/oauth/callback

3. Configure in Nango Dashboard

Copy Client ID and Secret to Nango → Integrations → notion

Dropbox

1. Create Dropbox App

2. Configure Permissions

✓ files.metadata.read
✓ files.content.read

3. Set Redirect URI

https://api.nango.dev/oauth/callback

Environment Variables Reference

VariableRequiredDescription
NEXT_PUBLIC_NANGO_ENABLED✓Enable/disable Nango feature
NANGO_SECRET_KEY✓Backend secret key from Nango dashboard
NANGO_WEBHOOK_SECRETWebhook signature verification
NANGO_HOSTAPI endpoint (default: https://api.nango.dev)
NEXT_PUBLIC_CONNECTORS_ENABLEDEnable connectors system
CONNECTORS_SHOW_ON_DASHBOARDShow connectors on Document Dashboard
NANGO_SYNC_INTERVAL_HOURSAuto-sync interval (0 = manual only)
NANGO_MAX_FILES_PER_SYNCMaximum files per sync batch (default: 100)

Admin Configuration

Admins can manage connectors through the Configuration Dashboard without code changes.

Access Config Dashboard

npm run config
# Open http://localhost:3333
# Navigate to "🔗 Connectors" tab

Available Controls

  • Enable/Disable Connectors: Toggle entire feature on/off
  • Dashboard Visibility: Show/hide connectors section
  • Per-Provider Settings: Enable/disable individual providers
  • Connection Statistics: View connected users, sync rates
  • Reset to Defaults: Restore default provider configuration

Document Sync Workflow

  1. User clicks "Sync" on a connected provider
  2. Backend fetches file list from provider via Nango proxy
  3. For each file:
    • Download content via Nango
    • Parse with LlamaCloud
    • Generate embeddings with OpenAI
    • Store in Supabase with vector indexes
  4. Track in nango_sync_records table
  5. Return sync statistics (added, updated, deleted, failed)

Troubleshooting

"Failed to create connect session"

  • Check NEXT_PUBLIC_NANGO_ENABLED=true
  • Verify NANGO_SECRET_KEY matches your Nango dashboard
  • Ensure you're logged in to ChatRAG
  • Check provider is configured in Nango integrations

Sync succeeded but no documents appeared

  • Verify folder contains files (not empty)
  • Check file types are supported (PDF, DOC, DOCX, TXT)
  • Ensure you have read access to the files
  • Check LlamaCloud/OpenAI API logs for parsing errors

Connection disconnects after ~1 hour

  • This happens with Nango-provided development credentials
  • Solution: Configure your own OAuth credentials for production
  • See Provider Setup section above

Notion pages show flat list (no hierarchy)

  • API filtering may not be working correctly
  • Check browser Network tab: /api/nango/notion/pages?mode=root
  • Verify response includes correct parent types

Debug Commands

# Test Nango connection
node scripts/diagnose-nango-oauth.js

# Check connector configuration
curl http://localhost:3000/api/config/connectors | jq .

# List enabled providers only
curl http://localhost:3000/api/config/connectors | \
  jq '.providers[] | select(.enabled == true) | .provider'

# View sync diagnostics
node scripts/diagnose-nango-sync.js
← Previous: RAG SystemNext: MCP Integration →