{"slug":"internal/development/COMPLETE_PROVIDER_AGNOSTIC_GUIDE","title":"Complete Provider-Agnostic Architecture Guide","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/development/COMPLETE_PROVIDER_AGNOSTIC_GUIDE.mdx","bytes":14066,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Executive Summary\n\nIntegrateWise is now **completely provider-agnostic** across all four critical layers:\n\n1. **Authentication** (Supabase Auth or Clerk)\n2. **Database** (Supabase PostgreSQL or Cloudflare D1)\n3. **AI Model** (Claude, GPT, or Groq)\n4. **Agent Orchestration** (Vercel AI or LangChain)\n\n**Change providers with environment variables only. Zero code changes required.**\n\n---\n\n## Four-Layer Architecture\n\n### Layer 1: Authentication Provider\n\n| Provider | Configuration | Best For |\n|----------|---------------|----------|\n| **Supabase Auth** | `NEXT_PUBLIC_AUTH_PROVIDER=supabase` | Full-featured auth, RLS policies |\n| **Clerk Auth** | `NEXT_PUBLIC_AUTH_PROVIDER=clerk` | Modern UX, multi-tenancy |\n\n**Location:** `lib/auth/factory.ts` → `getAuthProvider()`\n\n### Layer 2: Database Provider\n\n| Provider | Configuration | Best For |\n|----------|---------------|----------|\n| **Supabase PostgreSQL** | `NEXT_PUBLIC_DB_PROVIDER=supabase` | Complex queries, full SQL |\n| **Cloudflare D1** | `NEXT_PUBLIC_DB_PROVIDER=d1` | Edge-first, zero cold starts |\n\n**Location:** `lib/db/factory.ts` → `getDatabaseProvider()`\n\n### Layer 3: AI Provider\n\n| Provider | Configuration | Best For |\n|----------|---------------|----------|\n| **Claude (Anthropic)** | `NEXT_PUBLIC_AI_PROVIDER=claude` | Quality, reasoning |\n| **GPT (OpenAI)** | `NEXT_PUBLIC_AI_PROVIDER=gpt` | Versatility, balanced |\n| **Groq** | `NEXT_PUBLIC_AI_PROVIDER=groq` | Speed, cost-efficiency |\n\n**Location:** `lib/ai/factory.ts` → `getAIProvider()`\n\n### Layer 4: Agent Provider\n\n| Provider | Configuration | Best For |\n|----------|---------------|----------|\n| **Vercel AI** | `NEXT_PUBLIC_AGENT_PROVIDER=vercel-ai` | Simplicity, zero deps |\n| **LangChain** | `NEXT_PUBLIC_AGENT_PROVIDER=langchain` | Complex workflows, tools |\n\n**Location:** `lib/agent/factory.ts` → `getAgentProvider()`\n\n---\n\n## Pre-Built Configuration Templates\n\n### Template 1: Full Supabase Stack (Proven, Established)\n\n**Use Case:** Traditional SaaS, complex queries, full PostgreSQL features\n\n**Environment:**\n```bash\n# Auth\nNEXT_PUBLIC_AUTH_PROVIDER=supabase\nNEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co\nNEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...\nSUPABASE_SERVICE_ROLE_KEY=eyJhbGc...\n\n# Database\nNEXT_PUBLIC_DB_PROVIDER=supabase\n\n# AI\nNEXT_PUBLIC_AI_PROVIDER=claude\nANTHROPIC_API_KEY=sk-ant-...\n\n# Agent\nNEXT_PUBLIC_AGENT_PROVIDER=vercel-ai\n```\n\n**Costs:** $$$ (Supabase + Anthropic)\n**Setup Time:** 30 minutes\n**Reliability:** ⭐⭐⭐⭐⭐\n\n---\n\n### Template 2: Full Cloudflare Stack (Modern, Edge-First)\n\n**Use Case:** Edge computing, serverless-first, Cloudflare ecosystem\n\n**Environment:**\n```bash\n# Auth\nNEXT_PUBLIC_AUTH_PROVIDER=clerk\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...\nCLERK_SECRET_KEY=sk_live_...\n\n# Database\nNEXT_PUBLIC_DB_PROVIDER=d1\n# Add to wrangler.toml:\n# [[d1_databases]]\n# binding = \"DB\"\n# database_name = \"integratewise\"\n# database_id = \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n\n# AI\nNEXT_PUBLIC_AI_PROVIDER=gpt\nOPENAI_API_KEY=sk-...\n\n# Agent\nNEXT_PUBLIC_AGENT_PROVIDER=vercel-ai\n```\n\n**Costs:** $ (Cloudflare free tier + OpenAI pay-as-you-go)\n**Setup Time:** 45 minutes\n**Reliability:** ⭐⭐⭐⭐\n\n---\n\n### Template 3: Cost-Optimized Stack (Budget-Conscious)\n\n**Use Case:** Cost-sensitive, speed important, MVP/startup\n\n**Environment:**\n```bash\n# Auth\nNEXT_PUBLIC_AUTH_PROVIDER=clerk\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...\nCLERK_SECRET_KEY=sk_test_...\n\n# Database\nNEXT_PUBLIC_DB_PROVIDER=d1\n# Deploy to Cloudflare (free tier available)\n\n# AI\nNEXT_PUBLIC_AI_PROVIDER=groq\nGROQ_API_KEY=gsk_...  # Free tier available\n# Use Vercel AI Gateway for rate limiting\nNEXT_PUBLIC_USE_AI_GATEWAY=true\n\n# Agent\nNEXT_PUBLIC_AGENT_PROVIDER=vercel-ai\n```\n\n**Costs:** $ (Primarily AI usage, mostly free)\n**Setup Time:** 20 minutes\n**Reliability:** ⭐⭐⭐⭐\n\n---\n\n### Template 4: Hybrid Stack (Best Performance)\n\n**Use Case:** High-performance, mixed requirements, enterprise\n\n**Environment:**\n```bash\n# Auth\nNEXT_PUBLIC_AUTH_PROVIDER=supabase\nNEXT_PUBLIC_SUPABASE_URL=...\nNEXT_PUBLIC_SUPABASE_ANON_KEY=...\n\n# Database\nNEXT_PUBLIC_DB_PROVIDER=d1\n# Use D1 for performance, Supabase for auth\n\n# AI\nNEXT_PUBLIC_AI_PROVIDER=groq  # For speed\n# Fallback to Claude for complex reasoning\nGROQ_API_KEY=...\nANTHROPIC_API_KEY=...\n\n# Agent\nNEXT_PUBLIC_AGENT_PROVIDER=langchain  # For complex workflows\n```\n\n**Costs:** $$ (Flexible)\n**Setup Time:** 60 minutes\n**Reliability:** ⭐⭐⭐⭐⭐\n\n---\n\n## Usage Examples\n\n### Example 1: Provider-Agnostic User Fetch\n\n```typescript\n// Works with Supabase Auth OR Clerk\n\nexport async function getUserAction() {\n  const auth = getAuthProvider()\n  const user = await auth.getCurrentUser()\n  return user\n}\n```\n\n### Example 2: Provider-Agnostic Database Query\n\n```typescript\n// Works with Supabase PostgreSQL OR D1\n\nexport async function fetchUserData(userId: string) {\n  const db = getDatabaseProvider()\n  const result = await db.query(\n    'SELECT * FROM users WHERE id = ?',\n    [userId]\n  )\n  return result.data?.[0]\n}\n```\n\n### Example 3: Provider-Agnostic AI Generation\n\n```typescript\n// Works with Claude, GPT, or Groq\n\nexport async function generateSummary(text: string) {\n  const ai = getAIProvider()\n  const response = await ai.generate(\n    `Summarize this text: ${text}`,\n    { maxTokens: 200 }\n  )\n  return response.content\n}\n```\n\n### Example 4: Provider-Agnostic Agent Execution\n\n```typescript\n// Works with Vercel AI or LangChain\n\nexport async function executeAnalysis(task: string) {\n  const agents = getAgentProvider()\n  const result = await agents.executeAgent(\n    {\n      id: 'analyst_1',\n      name: 'Analyst',\n      role: 'analyst',\n      capabilities: ['analysis'],\n      tools: ['data_query']\n    },\n    { id: 'task_1', description: task }\n  )\n  return result.output\n}\n```\n\n### Example 5: Combining All Layers\n\n```typescript\n// Use all four layers together\n\nexport async function complexWorkflow(userId: string, query: string) {\n  // 1. Get user (auth agnostic)\n  const auth = getAuthProvider()\n  const user = await auth.getCurrentUser()\n\n  // 2. Fetch data (db agnostic)\n  const db = getDatabaseProvider()\n  const data = await db.query(\n    'SELECT * FROM reports WHERE user_id = ?',\n    [userId]\n  )\n\n  // 3. Generate analysis (ai agnostic)\n  const ai = getAIProvider()\n  const analysis = await ai.generate(\n    `Analyze this data: ${JSON.stringify(data)}`,\n    { temperature: 0.7 }\n  )\n\n  // 4. Execute agents (agent agnostic)\n  const agents = getAgentProvider()\n  const result = await agents.executeAgent(\n    {\n      id: 'executor',\n      name: 'Executor',\n      role: 'executor',\n      capabilities: ['execution'],\n      tools: ['api_call']\n    },\n    { id: 'task', description: analysis.content }\n  )\n\n  return result.output\n}\n```\n\n---\n\n## Switching Providers\n\n### Switch Auth Provider\n\n```bash\n# Current: Supabase Auth\n# Target: Clerk Auth\n\n# 1. Update .env.local\nNEXT_PUBLIC_AUTH_PROVIDER=clerk\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...\nCLERK_SECRET_KEY=sk_...\n\n# 2. Add ClerkProvider to layout (if not already done)\n# 3. Remove Supabase env vars (optional)\n\n# 4. Restart dev server\n# Done! All code using getAuthProvider() automatically uses Clerk\n```\n\n### Switch Database Provider\n\n```bash\n# Current: Supabase PostgreSQL\n# Target: Cloudflare D1\n\n# 1. Set up D1 (add to wrangler.toml)\n[[d1_databases]]\nbinding = \"DB\"\ndatabase_name = \"integratewise\"\ndatabase_id = \"...\"\n\n# 2. Migrate schema to D1 (see migration guide)\n\n# 3. Update .env.local\nNEXT_PUBLIC_DB_PROVIDER=d1\n\n# 4. Restart dev server\n# Done! All code using getDatabaseProvider() automatically uses D1\n```\n\n### Switch AI Provider\n\n```bash\n# Current: Claude\n# Target: Groq (for speed/cost)\n\n# 1. Update .env.local\nNEXT_PUBLIC_AI_PROVIDER=groq\nGROQ_API_KEY=gsk_...\n\n# 2. Restart dev server\n# Done! All code using getAIProvider() automatically uses Groq\n```\n\n### Switch Agent Provider\n\n```bash\n# Current: Vercel AI\n# Target: LangChain (for complex workflows)\n\n# 1. Update .env.local\nNEXT_PUBLIC_AGENT_PROVIDER=langchain\n\n# 2. Install LangChain (if needed)\n# pnpm add langchain\n\n# 3. Restart dev server\n# Done! All code using getAgentProvider() automatically uses LangChain\n```\n\n---\n\n## Helper Functions for Provider Detection\n\n```typescript\n// Auth Detection\n\nif (isClerkAuth()) {\n  // Clerk-specific logic\n}\n\n// Database Detection\n\nif (isD1Database()) {\n  // D1-specific optimization\n}\n\n// AI Detection\n\nif (isGroqAI()) {\n  // Use Groq's fast inference for real-time tasks\n}\n\n// Agent Detection\n\nif (isLangChainAgent()) {\n  // Use LangChain's advanced features\n}\n```\n\n---\n\n## Testing All Combinations\n\n**Matrix:** 2 Auth × 2 DB × 3 AI × 2 Agent = **24 combinations**\n\n### Quick Test Script\n\n```bash\n#!/bin/bash\n\n# Test all combinations\nfor AUTH in supabase clerk; do\n  for DB in supabase d1; do\n    for AI in claude gpt groq; do\n      for AGENT in vercel-ai langchain; do\n        echo \"Testing: $AUTH + $DB + $AI + $AGENT\"\n        export NEXT_PUBLIC_AUTH_PROVIDER=$AUTH\n        export NEXT_PUBLIC_DB_PROVIDER=$DB\n        export NEXT_PUBLIC_AI_PROVIDER=$AI\n        export NEXT_PUBLIC_AGENT_PROVIDER=$AGENT\n        \n        pnpm build 2>&1 | grep -E \"error|Error\" && echo \"✗ FAILED\" || echo \"✓ PASSED\"\n      done\n    done\n  done\ndone\n```\n\n---\n\n## File Structure\n\n```\napps/web/lib/\n├── auth/\n│   ├── types.ts\n│   ├── env.ts\n│   ├── factory.ts\n│   └── providers/\n│       ├── supabase-auth.ts\n│       └── clerk-auth.ts\n├── db/\n│   ├── types.ts\n│   ├── env.ts\n│   ├── factory.ts\n│   └── providers/\n│       ├── supabase-db.ts\n│       └── d1-db.ts\n├── ai/\n│   ├── types.ts\n│   ├── env.ts\n│   ├── factory.ts\n│   └── providers/\n│       ├── claude-ai.ts\n│       ├── gpt-ai.ts\n│       └── groq-ai.ts\n└── agent/\n    ├── types.ts\n    ├── env.ts\n    ├── factory.ts\n    └── providers/\n        ├── vercel-ai-agent.ts\n        └── langchain-agent.ts\n```\n\n---\n\n## Deployment Considerations\n\n### For Supabase Stack\n- Keep Supabase service connected\n- Use environment variables for secrets\n- No additional configuration needed\n\n### For Cloudflare Stack\n- Deploy to Cloudflare Workers\n- Configure wrangler.toml for D1\n- Set environment variables in Vercel/Cloudflare\n\n### For Mixed Stack\n- Configure all relevant services\n- Test all provider combinations\n- Monitor costs per provider\n\n---\n\n## Best Practices\n\n1. **Always use factory functions** - Never import providers directly\n2. **Keep providers consistent per deployment** - Don't mix for testing in prod\n3. **Monitor provider performance** - Track latency per provider\n4. **Use appropriate provider for task**:\n   - Claude: Complex reasoning\n   - GPT: General-purpose\n   - Groq: Real-time/speed-critical\n5. **Cache provider instances** - Factories handle this automatically\n6. **Test all combinations** - Ensure cross-provider compatibility\n7. **Document provider choice** - Note why you chose each provider\n8. **Plan migration paths** - Know how to switch if needed\n\n---\n\n## Migration from One Stack to Another\n\n### From Supabase-only to Cloudflare-first\n\n```bash\n# Phase 1: Keep auth, migrate DB\nNEXT_PUBLIC_AUTH_PROVIDER=supabase    # Keep existing\nNEXT_PUBLIC_DB_PROVIDER=d1             # New\n# Migrate schema to D1 and test\n\n# Phase 2: Migrate auth\nNEXT_PUBLIC_AUTH_PROVIDER=clerk        # New\nNEXT_PUBLIC_DB_PROVIDER=d1             # Current\n# Update auth provider, test\n\n# Phase 3: Optimize AI/Agent\nNEXT_PUBLIC_AI_PROVIDER=groq           # For speed\nNEXT_PUBLIC_AGENT_PROVIDER=langchain   # For complexity\n```\n\n---\n\n## Troubleshooting\n\n### \"Unknown auth provider\" Error\n- Check `NEXT_PUBLIC_AUTH_PROVIDER` env var is set to `supabase` or `clerk`\n- Verify required API keys are present\n\n### \"Database connection failed\"\n- Check `NEXT_PUBLIC_DB_PROVIDER` is `supabase` or `d1`\n- Verify database credentials\n- Check D1 binding in wrangler.toml\n\n### \"AI provider timeout\"\n- Check API key validity\n- Verify network connectivity\n- Try Groq for faster responses\n\n### \"Agent execution failed\"\n- Check `NEXT_PUBLIC_AGENT_PROVIDER` value\n- Verify agent config is valid\n- Check tools are registered\n\n---\n\n## Performance Metrics\n\n| Metric | Supabase | D1 | Claude | GPT | Groq |\n|--------|----------|-----|--------|-----|------|\n| Latency | 50-200ms | 10-50ms | 1-3s | 0.5-2s | 0.2-0.8s |\n| Cost/M | $50-200 | $0-5 | $15 | $1-5 | $0.5-2 |\n| Throughput | High | Very High | Medium | High | Very High |\n\n---\n\n## Support Matrix\n\nAll factory functions follow this pattern:\n\n```typescript\n// Pattern: Get {Provider} → Use interface\nconst provider = get{Provider}Provider()\nawait provider.{method}()\n\n// Examples:\nconst auth = getAuthProvider()\nconst db = getDatabaseProvider()\nconst ai = getAIProvider()\nconst agents = getAgentProvider()\n```\n\nAll code is **100% TypeScript-safe** with full autocomplete support.\n\n---\n\nThis completes the four-layer provider-agnostic architecture. Choose your providers, deploy, and switch anytime with zero code changes.\n"}