AI Integration Overview

User types message
    |
    v
React Hook (useAIChat / useAICompletion)
    |--- Manages message history
    |--- Handles streaming state
    |--- Triggers credit animation
    |
    v
API Route (/api/ai/stream or /api/ai/chat)
    |--- 1. Feature guard (is chat mode enabled?)
    |--- 2. Authentication (Clerk → DB user)
    |--- 3. Rate limit check (global burst + credit balance)
    |--- 4. Credit deduction (BEFORE processing)
    |--- 5. Zod request validation
    |
    v
AI Service (ai-service.ts)
    |--- Resolves model aliases
    |--- Creates provider instance (cached)
    |--- Routes to correct provider
    |
    v
Provider (OpenAI / Anthropic / Google / xAI)
    |--- Sends request to provider API
    |--- Handles retries with exponential backoff
    |--- Streams response chunks via SSE
    |
    v
Response flows back
    |--- Usage tracked to database (non-blocking)
    |--- Credit balance invalidated in TanStack Query cache
    |--- Message displayed in chat UI

export function getActiveProvider(): AIProvider | null {
  // If provider is explicitly set, use it (AI_API_KEY can serve as its key)
  if (aiConfig.AI_PROVIDER) {
    return aiConfig.AI_PROVIDER
  }

  // Auto-detect based on available API keys (Anthropic preferred)
  if (aiConfig.ANTHROPIC_API_KEY) return 'anthropic'
  if (aiConfig.OPENAI_API_KEY) return 'openai'
  if (aiConfig.GOOGLE_AI_API_KEY) return 'google'
  if (aiConfig.XAI_API_KEY) return 'xai'

  return null
}

export const DEFAULT_MODELS: Record<AIProvider, string> = {
  openai: 'gpt-5-nano',
  anthropic: 'claude-haiku-4-5-20251001',
  google: 'gemini-2.5-flash',
  xai: 'grok-4-1-fast-reasoning',
}

export const AI_CHAT_FEATURES = {
  /**
   * RAG Chat (Modern UI)
   * Routes: /dashboard/chat-rag, /api/ai/rag/*
   * Features: Modern chat UI, Knowledge Base integration, Source Attribution
   */
  ragChat: process.env.NEXT_PUBLIC_AI_RAG_CHAT_ENABLED !== 'false',

  /**
   * LLM Chat (Direct Chat)
   * Routes: /dashboard/chat-llm, /api/ai/chat, /api/ai/stream
   * Features: Modern chat UI, Direct LLM conversation, Streaming
   */
  llmChat: process.env.NEXT_PUBLIC_AI_LLM_CHAT_ENABLED !== 'false',

  /**
   * Vision Chat (Image Analysis in LLM Chat)
   * Extends LLM Chat with image upload and analysis capabilities.
   * Requires LLM Chat to be enabled. Only active when BOTH flags are true.
   * Features: Drag & Drop, Paste, File picker, Base64 image transport
   */
  visionChat:
    process.env.NEXT_PUBLIC_AI_LLM_CHAT_ENABLED !== 'false' &&
    process.env.NEXT_PUBLIC_AI_VISION_ENABLED !== 'false',

  /**
   * PDF Chat (Document Analysis in LLM Chat)
   * Extends LLM Chat with PDF upload and text extraction capabilities.
   * Requires LLM Chat to be enabled. Only active when BOTH flags are true.
   * Features: Drag & Drop, File picker, server-side text extraction, all providers
   */
  pdfChat:
    process.env.NEXT_PUBLIC_AI_LLM_CHAT_ENABLED !== 'false' &&
    process.env.NEXT_PUBLIC_AI_PDF_CHAT_ENABLED !== 'false',

  /**
   * Audio Input (Speech-to-Text in LLM Chat)
   * Extends LLM Chat with microphone recording and Whisper transcription.
   * Requires LLM Chat to be enabled. Only active when BOTH flags are true.
   * Features: MediaRecorder, Whisper STT, editable transcript in input field
   */
  audioInput:
    process.env.NEXT_PUBLIC_AI_LLM_CHAT_ENABLED !== 'false' &&
    process.env.NEXT_PUBLIC_AI_AUDIO_INPUT_ENABLED !== 'false',

  /**
   * Image Generation (Text-to-Image)
   * Routes: /dashboard/image-gen, /api/ai/image-gen
   * Features: GPT Image models, multiple sizes/qualities/formats, transparent backgrounds
   * Standalone feature — does NOT require LLM Chat to be enabled.
   */
  imageGen: process.env.NEXT_PUBLIC_AI_IMAGE_GEN_ENABLED !== 'false',

  /**
   * Content Generator (Template-based Text Generation)
   * Routes: /dashboard/content, /api/ai/generate-content
   * Features: 5 templates (Email, Product, Blog, Social, Marketing), tone/language/length controls, streaming output
   * Standalone feature — does NOT require LLM Chat to be enabled.
   */
  contentGen: process.env.NEXT_PUBLIC_AI_CONTENT_GEN_ENABLED !== 'false',

} as const

apps/boilerplate/src/
├── lib/
│   └── ai/
│       ├── config.ts            # Central config, models, rate limits, env validation
│       ├── types.ts             # Shared TypeScript types (Message, Provider, etc.)
│       ├── feature-flags.ts     # AI_CHAT_FEATURES, guard functions
│       ├── route-guards.ts      # API + page guards for feature flags
│       ├── ai-service.ts        # High-level service (wraps provider factory)
│       ├── provider-factory.ts  # Creates/caches provider instances
│       ├── providers/
│       │   ├── base-provider.ts # Abstract class with retry logic
│       │   ├── openai.ts        # OpenAI implementation
│       │   ├── anthropic.ts     # Anthropic implementation
│       │   ├── google.ts        # Google AI implementation
│       │   └── xai.ts           # xAI implementation
│       ├── rag-service.ts       # RAG pipeline (search → context → answer)
│       ├── rag-search.ts        # pgvector similarity search
│       ├── rate-limiter.ts      # Global burst + tier-based limiting
│       ├── usage-tracker.ts     # Token/cost tracking to database
│       ├── image-gen/
│       │   ├── config.ts        # Model configs, sizes, quality options
│       │   ├── service.ts       # OpenAI image generation service
│       │   └── types.ts         # Image generation TypeScript types
│       ├── content-gen/
│       │   ├── config.ts        # Template definitions, prompt builder, UI labels
│       │   ├── service.ts       # Content generation AI service wrapper
│       │   └── types.ts         # Content generator TypeScript types
│       ├── sse-parser.ts        # Shared SSE stream parser with error handling
│       ├── quick-prompts.ts     # Configurable suggestion buttons
│       └── errors.ts            # Error class hierarchy
├── hooks/
│   ├── use-ai.ts               # React hooks (useAIChat, useAICompletion, etc.)
│   ├── use-image-gen.ts        # Image generation hook with history
│   ├── use-content-generator.ts # Content generator hook with SSE streaming
│   └── use-audio-recorder.ts   # Audio recording hook (MediaRecorder API)
├── app/
│   └── api/
│       └── ai/
│           ├── stream/route.ts          # POST — SSE streaming endpoint
│           ├── chat/route.ts            # POST — Synchronous chat endpoint
│           ├── speech-to-text/route.ts  # POST — Audio transcription (Whisper)
│           ├── image-gen/route.ts       # POST — Image generation endpoint
│           ├── generate-content/route.ts # POST — Content generation endpoint
│           ├── usage/route.ts           # GET — Usage statistics endpoint
│           └── rag/
│               ├── ask/route.ts         # POST — RAG question answering
│               └── conversations/       # CRUD for conversation history
└── components/
    └── ai/
        ├── chat/                # Chat UI components (12 components)
        ├── image-gen/           # Image generation UI (4 components)
        └── content-gen/         # Content generator UI (5 components)