Building Your First AYW Bot: A Step-by-Step Guide

te them to the appropriate specialist bot 4. Maintain a helpful, human-guided tone

Always be polite, concise, and guide users to the right destination.`, temperature: 0.7, maxTokens: 500 };

### Step 6: Build the Chat Service with OpenAI
Create `apps/backend/src/services/chatbotService.ts`:  

import OpenAI from 'openai'; import { PrismaClient } from '@prisma/client'; import { BotConfig, welcomeBot, supportBot, salesBot, feedbackBot } from './botConfig';

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

const botConfigs: Record<string, BotConfig> = { welcome: welcomeBot, support: supportBot, sales: salesBot, feedback: feedbackBot };

export class ChatbotService { async processMessage({ message, conversationId, botType, userId }: { message: string; conversationId?: string; botType: string; userId?: string; }) { const config = botConfigs[botType] || welcomeBot;

// Create or get conversation
let conversation;
if (conversationId) {
  conversation = await prisma.conversation.findUnique({
    where: { id: conversationId }
  });
} else {
  conversation = await prisma.conversation.create({
    data: {
      botType,
      userId,
      status: 'active'
    }
  });
}

// Save user message
await prisma.message.create({
  data: {
    conversationId: conversation.id,
    role: 'user',
    content: message
  }
});

// Get conversation history
const history = await prisma.message.findMany({
  where: { conversationId: conversation.id },
  orderBy: { createdAt: 'asc' },
  take: 10
});

// Call OpenAI with human-guided system prompt
const completion = await openai.chat.completions.create({
  model: 'gpt-4-turbo-preview',
  messages: [
    { role: 'system', content: config.systemPrompt },
    ...history.map(msg => ({
      role: msg.role as 'user' | 'assistant',
      content: msg.content
    }))
  ],
  temperature: config.temperature,
  max_tokens: config.maxTokens
});

const botResponse = completion.choices[0].message.content;

// Save bot response
await prisma.message.create({
  data: {
    conversationId: conversation.id,
    role: 'assistant',
    content: botResponse,
    botType
  }
});

return {
  message: botResponse,
  conversationId: conversation.id,
  botType: config.type
};

} }

### Step 7: Build the Frontend Chat Interface
Create `apps/frontend/src/pages/ChatPage.tsx`:  

import { useState, useRef, useEffect } from 'react'; import { Send, Bot, User } from 'lucide-react'; import { chatbotService } from '../services/chatbotService';

interface Message { id: string; role: 'user' | 'assistant'; content: string; timestamp: Date; }

export default function ChatPage() { const [messages, setMessages] = useState<Message[]>([]); const [input, setInput] = useState(''); const [isLoading, setIsLoading] = useState(false); const messagesEndRef = useRef<HTMLDivElement>(null);

useEffect(() => { messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' }); }, [messages]);

const sendMessage = async () => { if (!input.trim()) return;

const userMessage: Message = {
  id: Date.now().toString(),
  role: 'user',
  content: input,
  timestamp: new Date()
};

setMessages(prev => [...prev, userMessage]);
setInput('');
setIsLoading(true);

try {
  const response = await chatbotService.sendMessage({
    message: input,
    botType: 'welcome'
  });

  const botMessage: Message = {
    id: (Date.now() + 1).toString(),
    role: 'assistant',
    content: response.message,
    timestamp: new Date()
  };

  setMessages(prev => [...prev, botMessage]);
} catch (error) {
  console.error('Failed to send message:', error);
} finally {
  setIsLoading(false);
}

};

return ( <div className="flex flex-col h-screen max-w-4xl mx-auto p-4"> <header className="mb-4"> <h1 className="text-2xl font-bold">AYW Chatbot Demo</h1> <p className="text-gray-600">Powered by human-guided AI</p> </header>

  <div className="flex-1 overflow-y-auto border rounded-lg p-4 space-y-4">
    {messages.map(msg => (
      <div
        key={msg.id}
        className={`flex ${msg.role === 'u

## Pitfall Guide
1. **Prisma Schema Sync Failure**: Running `npx prisma migrate dev` without subsequently executing `npx prisma generate` leaves the TypeScript client out of sync with the database schema, causing runtime `PrismaClient` type errors.
2. **Unbounded Context Window**: Omitting the `take: 10` constraint in `prisma.message.findMany()` allows conversation history to grow indefinitely, exhausting the LLM context window, increasing API costs, and degrading response latency.
3. **Environment Variable Leakage**: Committing `.env` files to version control exposes `DATABASE_URL` and `OPENAI_API_KEY`. Always enforce `.env` in `.gitignore` and validate CORS origins against `FRONTEND_URL` at the Express middleware level.
4. **Temperature Misconfiguration for Routing**: Setting `temperature` > 0.8 for intent-routing bots introduces stochastic behavior that breaks deterministic classification. Keep routing bots at `0.3–0.7` and reserve higher temperatures for creative/feedback bots.
5. **Conversation State Loss**: Failing to persist and pass `conversationId` across HTTP requests forces the backend to treat every message as a new session, destroying context continuity and breaking multi-turn routing logic.
6. **Blocking UI During Inference**: Neglecting the `isLoading` state or optimistic UI updates causes the frontend to freeze during OpenAI API latency. Always toggle loading states and implement scroll-to-bottom effects for smooth UX.

## Deliverables
- **📘 AYW Architecture Blueprint**: Visual diagram detailing the monorepo workspace structure, Prisma ORM relationships, Express routing middleware, and OpenAI inference pipeline.
- **✅ Deployment Checklist**: Step-by-step validation matrix covering environment validation, Prisma migration verification, CORS configuration, API key rotation, and frontend/backend health checks.
- **⚙️ Configuration Templates**: Pre-configured `.env` samples, `prisma/schema.prisma` definitions for `User`, `Conversation`, and `Message` models, and typed `BotConfig` interfaces ready for production scaling.