How to Build an AI Chatbot: Complete Step-by-Step Guide

# Install Node.js (v18+)
# Download from nodejs.org or use nvm:
nvm install 18
nvm use 18

# Verify installation
node --version  # Should show v18.x.x
npm --version   # Should show 9.x.x

# Install PostgreSQL (v14+)
# macOS: brew install postgresql@14
# Ubuntu: sudo apt install postgresql-14
# Windows: Download from postgresql.org

# Create project directory
mkdir ai-chatbot-demo
cd ai-chatbot-demo

# Initialize project
npm init -y

# Core dependencies
npm install express cors dotenv
npm install openai@^4.0.0
npm install pg ws
npm install uuid date-fns

# Development dependencies
npm install --save-dev nodemon typescript @types/node @types/express
npm install --save-dev @types/ws @types/pg

# Initialize TypeScript
npx tsc --init

# .env
PORT=3000
NODE_ENV=development

# OpenAI Configuration
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_MAX_TOKENS=2000
OPENAI_TEMPERATURE=0.7

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/chatbot_db

# Redis (optional, for caching)
REDIS_URL=redis://localhost:6379

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=20

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

-- schema.sql
CREATE TABLE conversations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id VARCHAR(255),
  title VARCHAR(255),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  metadata JSONB DEFAULT '{}'::jsonb
);

CREATE TABLE messages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
  role VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
  content TEXT NOT NULL,
  tokens INTEGER,
  created_at TIMESTAMP DEFAULT NOW(),
  metadata JSONB DEFAULT '{}'::jsonb
);

CREATE INDEX idx_conversations_user_id ON conversations(user_id);
CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
CREATE INDEX idx_messages_created_at ON messages(created_at);

// src/config/database.ts
import { Pool } from 'pg';
import dotenv from 'dotenv';

dotenv.config();

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
});

pool.on('error', (err) => {
  console.error('Unexpected database error:', err);
  process.exit(-1);
});

export default pool;

// src/services/llm.service.ts
import OpenAI from 'openai';
import dotenv from 'dotenv';

dotenv.config();

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

export interface ChatCompletionOptions {
  model?: string;
  temperature?: number;
  maxTokens?: number;
  stream?: boolean;
}

class LLMService {
  /**
   * Generate a chat completion
   */
  async generateResponse(
    messages: ChatMessage[],
    options: ChatCompletionOptions = {}
  ): Promise<string> {
    try {
      const response = await openai.chat.completions.create({
        model: options.model || process.env.OPENAI_MODEL || 'gpt-4-turbo-preview',
        messages,
        temperature: options.temperature ?? parseFloat(process.env.OPENAI_TEMPERATURE || '0.7'),
        max_tokens: options.maxTokens ?? parseInt(process.env.OPENAI_MAX_TOKENS || '2000'),
        stream: false,
      });

      return response.choices[0]?.message?.content || '';
    } catch (error) {
      console.error('LLM Service Error:', error);
      throw new Error('Failed to generate response from LLM');
    }
  }

  /**
   * Generate streaming response
   */
  async *generateStreamingResponse(
    messages: ChatMessage[],
    options: ChatCompletionOptions = {}
  ): AsyncGenerator<string> {
    try {
      const stream = await openai.chat.completions.create({
        model: options.model || process.env.OPENAI_MODEL || 'gpt-4-turbo-preview',
        messages,
        temperature: options.temperature ?? parseFloat(process.env.OPENAI_TEMPERATURE || '0.7'),
        max_tokens: options.maxTokens ?? parseInt(process.env.OPENAI_MAX_TOKENS || '2000'),
        stream: true,
      });

      for await (const chunk of stream) {
        const content = chunk.choices[0]?.delta?.content;
        if (content) {
          yield content;
        }
      }
    } catch (error) {
      console.error('LLM Streaming Error:', error);
      throw new Error('Failed to generate streaming response');
    }
  }

  /**
   * Count tokens in text (approximate)
   */
  estimateTokens(text: string): number {
    // Rough estimation: 1 token ≈ 4 characters
    return Math.ceil(text.length / 4);
  }
}

export default new LLMService();

// src/controllers/chat.controller.ts
import { Request, Response } from 'express';
import { v4 as uuidv4 } from 'uuid';
import pool from '../config/database';
import llmService, { ChatMessage } from '../services/llm.service';

class ChatController {
  /**
   * Create new conversation
   */
  async createConversation(req: Request, res: Response) {
    const { userId, title } = req.body;

    try {
      const result = await pool.query(
        'INSERT INTO conversations (id, user_id, title) VALUES ($1, $2, $3) RETURNING *',
        [uuidv4(), userId || 'anonymous', title || 'New Conversation']
      );

      res.json({
        success: true,
        conversation: result.rows[0],
      });
    } catch (error) {
      console.error('Create conversation error:', error);
      res.status(500).json({ success: false, error: 'Failed to create conversation' });
    }
  }

  /**
   * Send message and get response
   */
  async sendMessage(req: Request, res: Response) {
    const { conversationId, message, userId } = req.body;

    if (!conversationId || !message) {
      return res.status(400).json({
        success: false,
        error: 'conversationId and message are required'
      });
    }

    try {
      // Save user message
      await pool.query(
        'INSERT INTO messages (id, conversation_id, role, content, tokens) VALUES ($1, $2, $3, $4, $5)',
        [uuidv4(), conversationId, 'user', message, llmService.estimateTokens(message)]
      );

      // Get conversation history
      const historyResult = await pool.query(
        'SELECT role, content FROM messages WHERE conversation_id = $1 ORDER BY created_at ASC',
        [conversationId]
      );

      // Build messages array for LLM
      const messages: ChatMessage[] = [
        {
          role: 'system',
          content: `You are a helpful AI assistant. Provide clear, accurate, and friendly responses.
          Current date: ${new Date().toLocaleDateString()}.`,
        },
        ...historyResult.rows.map((row) => ({
          role: row.role as 'user' | 'assistant',
          content: row.content,
        })),
      ];

      // Generate response
      const assistantResponse = await llmService.generateResponse(messages);

      // Save assistant message
      await pool.query(
        'INSERT INTO messages (id, conversation_id, role, content, tokens) VALUES ($1, $2, $3, $4, $5)',
        [
          uuidv4(),
          conversationId,
          'assistant',
          assistantResponse,
          llmService.estimateTokens(assistantResponse),
        ]
      );

      // Update conversation timestamp
      await pool.query(
        'UPDATE conversations SET updated_at = NOW() WHERE id = $1',
        [conversationId]
      );

      res.json({
        success: true,
        response: assistantResponse,
      });
    } catch (error) {
      console.error('Send message error:', error);
      res.status(500).json({ success: false, error: 'Failed to process message' });
    }
  }

  /**
   * Get conversation history
   */
  async getConversation(req: Request, res: Response) {
    const { conversationId } = req.params;

    try {
      const conversationResult = await pool.query(
        'SELECT * FROM conversations WHERE id = $1',
        [conversationId]
      );

      if (conversationResult.rows.length === 0) {
        return res.status(404).json({ success: false, error: 'Conversation not found' });
      }

      const messagesResult = await pool.query(
        'SELECT * FROM messages WHERE conversation_id = $1 ORDER BY created_at ASC',
        [conversationId]
      );

      res.json({
        success: true,
        conversation: conversationResult.rows[0],
        messages: messagesResult.rows,
      });
    } catch (error) {
      console.error('Get conversation error:', error);
      res.status(500).json({ success: false, error: 'Failed to retrieve conversation' });
    }
  }

  /**
   * List user conversations
   */
  async listConversations(req: Request, res: Response) {
    const { userId } = req.query;

    try {
      const result = await pool.query(
        'SELECT * FROM conversations WHERE user_id = $1 ORDER BY updated_at DESC LIMIT 50',
        [userId || 'anonymous']
      );

      res.json({
        success: true,
        conversations: result.rows,
      });
    } catch (error) {
      console.error('List conversations error:', error);
      res.status(500).json({ success: false, error: 'Failed to list conversations' });
    }
  }
}

export default new ChatController();

// src/server.ts
import express from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import chatController from './controllers/chat.controller';

dotenv.config();

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
}));
app.use(express.json());

// Routes
app.post('/api/conversations', chatController.createConversation.bind(chatController));
app.post('/api/chat', chatController.sendMessage.bind(chatController));
app.get('/api/conversations/:conversationId', chatController.getConversation.bind(chatController));
app.get('/api/conversations', chatController.listConversations.bind(chatController));

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

// Start server
app.listen(PORT, () => {
  console.log(`🤖 Chatbot server running on port ${PORT}`);
  console.log(`📊 Environment: ${process.env.NODE_ENV}`);
});

// src/services/intent.service.ts
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export enum Intent {
  QUESTION = 'question',
  SUPPORT = 'support',
  BOOKING = 'booking',
  COMPLAINT = 'complaint',
  GREETING = 'greeting',
  FAREWELL = 'farewell',
  UNKNOWN = 'unknown',
}

export interface IntentResult {
  intent: Intent;
  confidence: number;
  entities: Record<string, any>;
}

class IntentService {
  private intentPatterns: Record<Intent, RegExp[]> = {
    [Intent.GREETING]: [
      /^(hi|hello|hey|good (morning|afternoon|evening))/i,
    ],
    [Intent.FAREWELL]: [
      /^(bye|goodbye|see you|thanks|thank you)/i,
    ],
    [Intent.SUPPORT]: [
      /(help|support|issue|problem|not working|error)/i,
    ],
    [Intent.BOOKING]: [
      /(book|schedule|appointment|reserve|meeting)/i,
    ],
    [Intent.COMPLAINT]: [
      /(complain|complaint|upset|angry|frustrated|terrible)/i,
    ],
  };

  /**
   * Detect intent using pattern matching (fast, free)
   */
  detectIntentFast(message: string): IntentResult {
    const normalized = message.trim().toLowerCase();

    for (const [intent, patterns] of Object.entries(this.intentPatterns)) {
      for (const pattern of patterns) {
        if (pattern.test(normalized)) {
          return {
            intent: intent as Intent,
            confidence: 0.8,
            entities: {},
          };
        }
      }
    }

    // Default to question intent
    return {
      intent: normalized.includes('?') ? Intent.QUESTION : Intent.UNKNOWN,
      confidence: 0.5,
      entities: {},
    };
  }

  /**
   * Detect intent using LLM (accurate, but uses API credits)
   */
  async detectIntentAI(message: string): Promise<IntentResult> {
    try {
      const response = await openai.chat.completions.create({
        model: 'gpt-3.5-turbo',
        messages: [
          {
            role: 'system',
            content: `Analyze the user's message and respond with valid JSON only:
{
  "intent": "question|support|booking|complaint|greeting|farewell|unknown",
  "confidence": 0-1,
  "entities": {
    "date": "extracted date if any",
    "time": "extracted time if any",
    "product": "product name if mentioned",
    "emotion": "detected emotion"
  }
}`,
          },
          {
            role: 'user',
            content: message,
          },
        ],
        temperature: 0.3,
        max_tokens: 200,
      });

      const content = response.choices[0]?.message?.content;
      if (!content) throw new Error('No response from LLM');

      return JSON.parse(content);
    } catch (error) {
      console.error('Intent detection error:', error);
      return this.detectIntentFast(message);
    }
  }

  /**
   * Extract entities from message
   */
  extractEntities(message: string): Record<string, any> {
    const entities: Record<string, any> = {};

    // Extract email
    const emailMatch = message.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
    if (emailMatch) entities.email = emailMatch[0];

    // Extract phone
    const phoneMatch = message.match(/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/);
    if (phoneMatch) entities.phone = phoneMatch[0];

    // Extract dates (simple patterns)
    const datePatterns = [
      /\b(tomorrow|today|yesterday)\b/i,
      /\b(\d{1,2})[\/\-](\d{1,2})[\/\-](\d{2,4})\b/,
      /\b(january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}/i,
    ];

    for (const pattern of datePatterns) {
      const match = message.match(pattern);
      if (match) {
        entities.date = match[0];
        break;
      }
    }

    return entities;
  }
}

export default new IntentService();

// src/services/sentiment.service.ts
export enum Sentiment {
  POSITIVE = 'positive',
  NEUTRAL = 'neutral',
  NEGATIVE = 'negative',
}

class SentimentService {
  private positiveWords = ['good', 'great', 'excellent', 'love', 'perfect', 'amazing', 'wonderful'];
  private negativeWords = ['bad', 'terrible', 'awful', 'hate', 'worst', 'horrible', 'disappointed'];

  /**
   * Analyze sentiment of message
   */
  analyzeSentiment(message: string): { sentiment: Sentiment; score: number } {
    const normalized = message.toLowerCase();
    let score = 0;

    // Count positive words
    for (const word of this.positiveWords) {
      if (normalized.includes(word)) score += 1;
    }

    // Count negative words
    for (const word of this.negativeWords) {
      if (normalized.includes(word)) score -= 1;
    }

    // Determine sentiment
    let sentiment: Sentiment;
    if (score > 0) sentiment = Sentiment.POSITIVE;
    else if (score < 0) sentiment = Sentiment.NEGATIVE;
    else sentiment = Sentiment.NEUTRAL;

    return { sentiment, score };
  }
}

export default new SentimentService();

// Add to chat.controller.ts
import intentService from '../services/intent.service';
import sentimentService from '../services/sentiment.service';

// In sendMessage method, before generating LLM response:
const intent = intentService.detectIntentFast(message);
const { sentiment } = sentimentService.analyzeSentiment(message);

// Modify system prompt based on intent and sentiment
let systemPrompt = 'You are a helpful AI assistant.';

if (sentiment === 'negative') {
  systemPrompt += ' The user seems frustrated. Be extra empathetic and helpful.';
}

if (intent.intent === 'complaint') {
  systemPrompt += ' This is a complaint. Acknowledge their concern and offer solutions.';
}

if (intent.intent === 'booking') {
  systemPrompt += ' Help the user schedule an appointment. Ask for necessary details: date, time, service type.';
}

// src/services/context.service.ts
import { ChatMessage } from './llm.service';

interface ContextWindow {
  messages: ChatMessage[];
  totalTokens: number;
}

class ContextService {
  private readonly MAX_TOKENS = 8000; // Leave room for response
  private readonly AVG_CHARS_PER_TOKEN = 4;

  /**
   * Build context window with sliding window strategy
   */
  buildContextWindow(
    messages: ChatMessage[],
    systemPrompt: string
  ): ContextWindow {
    const contextMessages: ChatMessage[] = [
      { role: 'system', content: systemPrompt },
    ];

    let totalTokens = this.estimateTokens(systemPrompt);

    // Always include last N messages that fit in window
    for (let i = messages.length - 1; i >= 0; i--) {
      const msg = messages[i];
      const msgTokens = this.estimateTokens(msg.content);

      if (totalTokens + msgTokens > this.MAX_TOKENS) {
        break;
      }

      contextMessages.unshift(msg);
      totalTokens += msgTokens;
    }

    return { messages: contextMessages, totalTokens };
  }

  /**
   * Summarize older messages to preserve context
   */
  async summarizeContext(
    messages: ChatMessage[],
    llmService: any
  ): Promise<string> {
    const conversationText = messages
      .map((m) => `${m.role}: ${m.content}`)
      .join('\n');

    const summary = await llmService.generateResponse([
      {
        role: 'system',
        content: 'Summarize the following conversation concisely, preserving key facts and context:',
      },
      {
        role: 'user',
        content: conversationText,
      },
    ], { maxTokens: 500, temperature: 0.3 });

    return summary;
  }

  /**
   * Extract and store conversation facts
   */
  extractFacts(messages: ChatMessage[]): Map<string, string> {
    const facts = new Map<string, string>();

    for (const msg of messages) {
      // Extract user information
      const emailMatch = msg.content.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
      if (emailMatch) facts.set('email', emailMatch[0]);

      const nameMatch = msg.content.match(/my name is (\w+)/i);
      if (nameMatch) facts.set('name', nameMatch[1]);

      const phoneMatch = msg.content.match(/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/);
      if (phoneMatch) facts.set('phone', phoneMatch[0]);
    }

    return facts;
  }

  private estimateTokens(text: string): number {
    return Math.ceil(text.length / this.AVG_CHARS_PER_TOKEN);
  }
}

export default new ContextService();

// First, add pgvector extension to PostgreSQL:
-- CREATE EXTENSION IF NOT EXISTS vector;
-- ALTER TABLE messages ADD COLUMN embedding vector(1536);

// src/services/embedding.service.ts
import OpenAI from 'openai';
import pool from '../config/database';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

class EmbeddingService {
  /**
   * Generate embedding for text
   */
  async generateEmbedding(text: string): Promise<number[]> {
    const response = await openai.embeddings.create({
      model: 'text-embedding-3-small',
      input: text,
    });

    return response.data[0].embedding;
  }

  /**
   * Store message embedding
   */
  async storeEmbedding(messageId: string, content: string): Promise<void> {
    const embedding = await this.generateEmbedding(content);

    await pool.query(
      'UPDATE messages SET embedding = $1 WHERE id = $2',
      [JSON.stringify(embedding), messageId]
    );
  }

  /**
   * Find semantically similar messages
   */
  async findSimilarMessages(
    query: string,
    conversationId: string,
    limit: number = 5
  ): Promise<any[]> {
    const queryEmbedding = await this.generateEmbedding(query);

    const result = await pool.query(
      `SELECT id, content, role,
       1 - (embedding <=> $1::vector) as similarity
       FROM messages
       WHERE conversation_id = $2 AND embedding IS NOT NULL
       ORDER BY embedding <=> $1::vector
       LIMIT $3`,
      [JSON.stringify(queryEmbedding), conversationId, limit]
    );

    return result.rows;
  }
}

export default new EmbeddingService();

// src/utils/prompts.ts
export interface PromptConfig {
  companyName: string;
  industry: string;
  tone: 'professional' | 'casual' | 'friendly';
  expertise: string[];
  guidelines: string[];
}

export class PromptBuilder {
  static buildSystemPrompt(config: PromptConfig): string {
    return `You are an AI assistant for ${config.companyName}, a company in the ${config.industry} industry.

PERSONALITY & TONE:
- Communicate in a ${config.tone} manner
- Be helpful, accurate, and concise
- Show expertise but avoid jargon unless necessary

EXPERTISE AREAS:
${config.expertise.map((e) => `- ${e}`).join('\n')}

GUIDELINES:
${config.guidelines.map((g) => `- ${g}`).join('\n')}

IMPORTANT RULES:
- Always provide sources when stating facts
- If you don't know something, admit it honestly
- Never make up information
- Protect user privacy - never ask for sensitive data unnecessarily
- If the query requires human expertise, suggest contacting support

Current date: ${new Date().toLocaleDateString()}
Current time: ${new Date().toLocaleTimeString()}`;
  }

  static buildRAGPrompt(context: string, query: string): string {
    return `Use the following context to answer the question. If the context doesn't contain enough information, say so.

CONTEXT:
${context}

QUESTION:
${query}

ANSWER:`;
  }
}

// Example usage:
const systemPrompt = PromptBuilder.buildSystemPrompt({
  companyName: 'Verlua',
  industry: 'Software Development & AI Solutions',
  tone: 'professional',
  expertise: [
    'AI chatbot development',
    'Custom software applications',
    'Web development',
    'API integrations',
  ],
  guidelines: [
    'Focus on technical accuracy',
    'Provide code examples when helpful',
    'Suggest best practices',
    'Recommend appropriate services when relevant',
  ],
});

// src/services/knowledge.service.ts
import embeddingService from './embedding.service';
import pool from '../config/database';

interface KnowledgeDocument {
  id: string;
  title: string;
  content: string;
  category: string;
  embedding?: number[];
}

class KnowledgeService {
  /**
   * Add document to knowledge base
   */
  async addDocument(doc: Omit<KnowledgeDocument, 'id'>): Promise<string> {
    const id = uuidv4();
    const embedding = await embeddingService.generateEmbedding(doc.content);

    await pool.query(
      `INSERT INTO knowledge_documents (id, title, content, category, embedding)
       VALUES ($1, $2, $3, $4, $5)`,
      [id, doc.title, doc.content, doc.category, JSON.stringify(embedding)]
    );

    return id;
  }

  /**
   * Search knowledge base
   */
  async search(query: string, limit: number = 3): Promise<KnowledgeDocument[]> {
    const queryEmbedding = await embeddingService.generateEmbedding(query);

    const result = await pool.query(
      `SELECT id, title, content, category,
       1 - (embedding <=> $1::vector) as similarity
       FROM knowledge_documents
       ORDER BY embedding <=> $1::vector
       LIMIT $2`,
      [JSON.stringify(queryEmbedding), limit]
    );

    return result.rows;
  }

  /**
   * Generate RAG-enhanced response
   */
  async generateRAGResponse(
    query: string,
    llmService: any
  ): Promise<string> {
    // Search knowledge base
    const relevantDocs = await this.search(query, 3);

    if (relevantDocs.length === 0) {
      return llmService.generateResponse([
        { role: 'user', content: query },
      ]);
    }

    // Build context from documents
    const context = relevantDocs
      .map((doc) => `${doc.title}:\n${doc.content}`)
      .join('\n\n---\n\n');

    // Generate response with context
    const prompt = PromptBuilder.buildRAGPrompt(context, query);

    return llmService.generateResponse([
      { role: 'system', content: 'You are a helpful assistant that answers questions based on provided context.' },
      { role: 'user', content: prompt },
    ]);
  }
}

export default new KnowledgeService();

// src/services/faq.service.ts
interface FAQ {
  question: string;
  answer: string;
  keywords: string[];
}

class FAQService {
  private faqs: FAQ[] = [
    {
      question: 'What are your business hours?',
      answer: 'We are open Monday-Friday, 9 AM to 6 PM EST.',
      keywords: ['hours', 'open', 'time', 'schedule'],
    },
    {
      question: 'How much does a chatbot cost?',
      answer: 'Custom chatbot pricing starts at $5,000 and varies based on features, integrations, and complexity. Contact us for a detailed quote.',
      keywords: ['price', 'cost', 'pricing', 'expensive'],
    },
    // Add more FAQs
  ];

  /**
   * Find matching FAQ
   */
  findFAQ(query: string): FAQ | null {
    const normalized = query.toLowerCase();

    for (const faq of this.faqs) {
      const matchCount = faq.keywords.filter((keyword) =>
        normalized.includes(keyword.toLowerCase())
      ).length;

      if (matchCount >= 2) {
        return faq;
      }
    }

    return null;
  }

  /**
   * Check if message is FAQ before calling LLM
   */
  async handleMessage(message: string, llmService: any): Promise<string> {
    const faq = this.findFAQ(message);

    if (faq) {
      // Return FAQ answer directly (faster, free)
      return faq.answer;
    }

    // Fall back to LLM
    return llmService.generateResponse([
      { role: 'user', content: message },
    ]);
  }
}

export default new FAQService();

// src/services/handoff.service.ts
export enum HandoffReason {
  USER_REQUEST = 'user_request',
  COMPLEX_QUERY = 'complex_query',
  NEGATIVE_SENTIMENT = 'negative_sentiment',
  REPEATED_CONFUSION = 'repeated_confusion',
}

interface HandoffTrigger {
  conversationId: string;
  reason: HandoffReason;
  timestamp: Date;
  context: string;
}

class HandoffService {
  private handoffThreshold = 3; // Failed attempts before handoff

  /**
   * Check if handoff is needed
   */
  shouldHandoff(
    conversation: any[],
    sentiment: string,
    intent: string
  ): HandoffReason | null {
    // User explicitly asks for human
    const lastMessage = conversation[conversation.length - 1]?.content.toLowerCase();
    if (lastMessage?.includes('human') || lastMessage?.includes('agent')) {
      return HandoffReason.USER_REQUEST;
    }

    // Repeated confusion or "I don't understand"
    const recentMessages = conversation.slice(-5);
    const confusionCount = recentMessages.filter((m) =>
      m.role === 'assistant' &&
      (m.content.includes("I don't understand") || m.content.includes("I'm not sure"))
    ).length;

    if (confusionCount >= this.handoffThreshold) {
      return HandoffReason.REPEATED_CONFUSION;
    }

    // Strong negative sentiment
    if (sentiment === 'negative') {
      return HandoffReason.NEGATIVE_SENTIMENT;
    }

    return null;
  }

  /**
   * Initiate handoff
   */
  async initiateHandoff(trigger: HandoffTrigger): Promise<void> {
    console.log('Handoff initiated:', trigger);

    // Here you would:
    // 1. Notify human agents (Slack, email, support system)
    // 2. Add conversation to support queue
    // 3. Send notification to user
    // 4. Log handoff for analytics

    // Example: Send to Slack
    // await notifySlack({
    //   channel: '#support',
    //   text: `Handoff needed: ${trigger.reason}`,
    //   conversationId: trigger.conversationId,
    // });
  }

  /**
   * Generate handoff message
   */
  getHandoffMessage(reason: HandoffReason): string {
    const messages = {
      [HandoffReason.USER_REQUEST]:
        "I'll connect you with a human agent right away. Please hold for a moment.",
      [HandoffReason.COMPLEX_QUERY]:
        "This query requires specialized expertise. Let me connect you with a team member who can help.",
      [HandoffReason.NEGATIVE_SENTIMENT]:
        "I understand you're frustrated. Let me get a human team member to assist you personally.",
      [HandoffReason.REPEATED_CONFUSION]:
        "I apologize for the confusion. A human agent will be able to help you better. Connecting you now.",
    };

    return messages[reason];
  }
}

export default new HandoffService();

// src/middleware/rateLimit.ts
import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

export const chatRateLimiter = rateLimit({
  store: new RedisStore({
    client: redis,
    prefix: 'rl:chat:',
  }),
  windowMs: 60 * 1000, // 1 minute
  max: 20, // 20 requests per minute
  message: 'Too many messages. Please wait a moment.',
  standardHeaders: true,
  legacyHeaders: false,
});

// Content moderation
export async function moderateContent(text: string): Promise<boolean> {
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

  const moderation = await openai.moderations.create({
    input: text,
  });

  return moderation.results[0].flagged;
}

// Apply to routes:
// app.post('/api/chat', chatRateLimiter, chatController.sendMessage);

# Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/server.js"]

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/chatbot
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - db
      - redis

  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: chatbot
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

# Production .env
NODE_ENV=production
PORT=3000

# Database (use connection pooling)
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

# OpenAI (use separate API key for production)
OPENAI_API_KEY=sk-prod-your-key
OPENAI_ORG_ID=org-your-org

# Security
JWT_SECRET=generate-strong-secret-here
ALLOWED_ORIGINS=https://yourdomain.com

# Monitoring
SENTRY_DSN=https://your-sentry-dsn
LOG_LEVEL=info

# Caching
REDIS_URL=rediss://default:password@host:6380

// tests/services/intent.service.test.ts
import intentService from '../../src/services/intent.service';

describe('IntentService', () => {
  describe('detectIntentFast', () => {
    it('should detect greeting intent', () => {
      const result = intentService.detectIntentFast('Hello there!');
      expect(result.intent).toBe('greeting');
      expect(result.confidence).toBeGreaterThan(0.7);
    });

    it('should detect support intent', () => {
      const result = intentService.detectIntentFast('I need help with my account');
      expect(result.intent).toBe('support');
    });

    it('should detect booking intent', () => {
      const result = intentService.detectIntentFast('I want to schedule an appointment');
      expect(result.intent).toBe('booking');
    });
  });

  describe('extractEntities', () => {
    it('should extract email addresses', () => {
      const entities = intentService.extractEntities('My email is john@example.com');
      expect(entities.email).toBe('john@example.com');
    });

    it('should extract phone numbers', () => {
      const entities = intentService.extractEntities('Call me at 555-123-4567');
      expect(entities.phone).toBe('555-123-4567');
    });
  });
});

// tests/integration/chat.test.ts
import request from 'supertest';
import app from '../../src/server';

describe('Chat API', () => {
  let conversationId: string;

  it('should create a new conversation', async () => {
    const response = await request(app)
      .post('/api/conversations')
      .send({ userId: 'test-user', title: 'Test Chat' })
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.conversation).toHaveProperty('id');
    conversationId = response.body.conversation.id;
  });

  it('should send a message and receive response', async () => {
    const response = await request(app)
      .post('/api/chat')
      .send({
        conversationId,
        message: 'What services do you offer?',
        userId: 'test-user',
      })
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.response).toBeTruthy();
    expect(typeof response.body.response).toBe('string');
  });

  it('should retrieve conversation history', async () => {
    const response = await request(app)
      .get(`/api/conversations/${conversationId}`)
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.messages).toBeInstanceOf(Array);
    expect(response.body.messages.length).toBeGreaterThan(0);
  });
});

// Performance monitoring
import { performance } from 'perf_hooks';

async function monitoredLLMCall(messages: ChatMessage[]) {
  const start = performance.now();

  try {
    const response = await llmService.generateResponse(messages);
    const duration = performance.now() - start;

    // Log metrics
    console.log({
      timestamp: new Date().toISOString(),
      duration,
      tokenCount: llmService.estimateTokens(response),
      success: true,
    });

    return response;
  } catch (error) {
    const duration = performance.now() - start;

    console.error({
      timestamp: new Date().toISOString(),
      duration,
      success: false,
      error: error.message,
    });

    throw error;
  }
}