@digilogiclabs/create-saas-app 1.0.1

package/src/templates/web/ui-auth-payments-ai-rag/template/docs/GETTING-STARTED.md

@@ -0,0 +1,457 @@
+# Getting Started with AI Knowledge Platform
+
+This guide will help you set up and customize your RAG-powered AI knowledge platform in under 10 minutes.
+
+## Prerequisites
+
+- **Node.js 18+**: [Download here](https://nodejs.org/)
+- **Supabase Account**: [Sign up for free](https://supabase.com/)
+- **OpenAI API Key**: [Get your API key](https://platform.openai.com/api-keys)
+- **Git**: For version control
+
+## 🚀 1-Minute Quick Start
+
+```bash
+# Create project
+npm create saas-app my-ai-platform --template=web-ai-rag
+cd my-ai-platform
+
+# Setup environment
+cp .env.example .env.local
+# Edit .env.local with your API keys
+
+# Initialize RAG system
+npm run setup:rag
+
+# Seed with sample data
+npm run seed:knowledge
+
+# Start development
+npm run dev
+```
+
+🎉 **Done!** Visit `http://localhost:3000/ai` to start chatting with your AI assistant.
+
+## 📝 Detailed Setup
+
+### Step 1: Environment Configuration
+
+Create and configure your `.env.local` file:
+
+```env
+# Supabase Database
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ0eXAi...your-anon-key
+SUPABASE_SERVICE_ROLE_KEY=eyJ0eXAi...your-service-role-key
+
+# OpenAI API
+OPENAI_API_KEY=sk-...your-openai-api-key
+
+# Optional Configuration
+NEXT_PUBLIC_APP_NAME=My AI Platform
+NODE_ENV=development
+```
+
+**Getting Your Keys:**
+
+1. **Supabase**:
+   - Create project at [supabase.com](https://supabase.com/)
+   - Go to Settings → API to find your keys
+   - Copy the URL and both keys
+
+2. **OpenAI**:
+   - Sign up at [platform.openai.com](https://platform.openai.com/)
+   - Go to API keys section
+   - Create a new secret key
+
+### Step 2: Database Setup
+
+The `setup:rag` script creates all necessary database tables and functions:
+
+```bash
+npm run setup:rag
+```
+
+This creates:
+- **Knowledge base table** with vector embeddings
+- **Search functions** for similarity and hybrid search
+- **Analytics functions** for usage tracking
+- **RLS policies** for security
+- **Sample data** to test with
+
+**Manual Setup (if script fails):**
+```bash
+# Connect to your Supabase project
+supabase login
+supabase link --project-ref your-project-ref
+
+# Apply migrations
+supabase db push
+
+# Generate TypeScript types
+npm run db:types
+```
+
+### Step 3: First Test
+
+1. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+2. Open your browser to `http://localhost:3000/ai`
+
+3. Try asking:
+   - "How do I get started?"
+   - "What features are available?"
+   - "Help me set up my knowledge base"
+
+You should see AI responses with source citations from your knowledge base.
+
+## 🎯 Domain Configuration
+
+Choose your domain focus to optimize the AI responses:
+
+### Generic Assistant (Default)
+```typescript
+// No changes needed - works out of the box
+```
+
+### Plant Care Platform
+```typescript
+// lib/rag/config.ts
+export const ragConfig = getRAGConfigForDomain('plants')
+```
+
+Update your knowledge base with plant-related content:
+```bash
+# Replace generic samples with plant knowledge
+npm run seed:knowledge -- --domain=plants
+```
+
+### E-commerce Assistant
+```typescript
+// lib/rag/config.ts
+export const ragConfig = getRAGConfigForDomain('ecommerce')
+```
+
+### Education Platform
+```typescript
+// lib/rag/config.ts
+export const ragConfig = getRAGConfigForDomain('education')
+```
+
+## 📚 Adding Your First Knowledge
+
+### Via Web Interface
+
+1. Go to `http://localhost:3000/ai` → Knowledge tab
+2. Click "Add Document"
+3. Fill in:
+   - **Title**: "Company Overview"
+   - **Category**: "general"
+   - **Content**: Your company information
+4. Save and test by asking "Tell me about the company"
+
+### Via API
+
+```bash
+curl -X POST http://localhost:3000/api/knowledge \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "Our company was founded in 2023...",
+    "category": "company-info",
+    "fields": {
+      "title": "Company History",
+      "tags": ["company", "history"]
+    }
+  }'
+```
+
+### Bulk Import
+
+```javascript
+// scripts/import-knowledge.js
+const documents = [
+  {
+    content: "FAQ: How to reset password...",
+    category: "faq",
+    fields: { title: "Password Reset Guide" }
+  },
+  // ... more documents
+]
+
+await ragSystem.bulkAddKnowledge(documents)
+```
+
+Run: `node scripts/import-knowledge.js`
+
+## 🔧 Customization Guide
+
+### 1. Branding & Styling
+
+Update your brand colors in `tailwind.config.js`:
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: '#eff6ff',
+          500: '#3b82f6', // Your primary color
+          900: '#1e3a8a'
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. AI Personality
+
+Customize the AI's personality in `lib/rag/config.ts`:
+
+```typescript
+generation: {
+  systemPrompt: `You are a helpful assistant for [Your Company].
+  Always be friendly and professional.
+  When you don't know something, admit it and offer to help find the answer.
+  Use a conversational tone and provide actionable advice.`,
+  temperature: 0.3, // Lower = more consistent, Higher = more creative
+  maxTokens: 800,
+}
+```
+
+### 3. Search Behavior
+
+Adjust search sensitivity:
+
+```typescript
+retrieval: {
+  topK: 8, // Number of documents to retrieve
+  confidenceThreshold: 0.75, // Minimum similarity score
+  hybridSearchWeight: {
+    vector: 0.7, // Semantic similarity weight
+    text: 0.3    // Keyword matching weight
+  }
+}
+```
+
+### 4. UI Components
+
+Replace the default chat interface:
+
+```typescript
+// app/ai/page.tsx
+import { MyCustomChatInterface } from '@/components/MyCustomChatInterface'
+
+export default function AIPage() {
+  return (
+    <MyCustomChatInterface
+      ragSystem={ragSystem}
+      theme="dark"
+      showWelcomeMessage={true}
+      customActions={['export', 'share', 'feedback']}
+    />
+  )
+}
+```
+
+## 📊 Monitoring & Analytics
+
+### View Built-in Analytics
+
+Navigate to `http://localhost:3000/ai` → Analytics tab to see:
+
+- Query volume and trends
+- Response confidence scores
+- Popular questions
+- Knowledge base growth
+- User satisfaction metrics
+
+### Custom Analytics
+
+```typescript
+// Get detailed analytics data
+const analytics = await ragSystem.getAnalytics('30d')
+
+console.log('Analytics Overview:', {
+  totalQueries: analytics.usage.totalQueries,
+  averageResponseTime: analytics.usage.averageResponseTime,
+  topQueries: analytics.performance.popularQueries.slice(0, 5),
+  knowledgeGrowth: analytics.knowledge.documentsAdded
+})
+```
+
+### Export Analytics
+
+```bash
+# Built-in export functionality
+curl http://localhost:3000/api/analytics/export?timeRange=7d > analytics.json
+```
+
+## 🚀 Production Deployment
+
+### Deploy to Vercel (Recommended)
+
+1. **Push to GitHub**:
+   ```bash
+   git add .
+   git commit -m "Initial AI platform setup"
+   git push origin main
+   ```
+
+2. **Connect to Vercel**:
+   - Go to [vercel.com](https://vercel.com/)
+   - Import your GitHub repository
+   - Add environment variables in Vercel dashboard
+
+3. **Configure Environment Variables**:
+   ```bash
+   vercel env add OPENAI_API_KEY production
+   vercel env add SUPABASE_SERVICE_ROLE_KEY production
+   vercel env add NEXT_PUBLIC_SUPABASE_URL production
+   vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY production
+   ```
+
+4. **Deploy**:
+   ```bash
+   vercel --prod
+   ```
+
+### Production Checklist
+
+- [ ] Environment variables configured
+- [ ] Database migrations applied to production
+- [ ] Rate limiting enabled
+- [ ] Analytics tracking set up
+- [ ] Error monitoring configured
+- [ ] Backup strategy implemented
+- [ ] SSL certificate active
+- [ ] Domain configured
+
+## 🔒 Security Best Practices
+
+### API Security
+
+1. **Rate Limiting**: Prevent API abuse
+   ```typescript
+   // middleware.ts
+   export async function middleware(request: NextRequest) {
+     const rateLimiter = new RateLimiter({
+       windowMs: 15 * 60 * 1000, // 15 minutes
+       max: 100 // requests per window
+     })
+
+     return rateLimiter.check(request)
+   }
+   ```
+
+2. **Input Validation**: Sanitize user inputs
+   ```typescript
+   import { z } from 'zod'
+
+   const querySchema = z.object({
+     query: z.string().min(1).max(500),
+     category: z.string().optional()
+   })
+   ```
+
+3. **Database Security**: Enable RLS policies
+   ```sql
+   -- Already included in setup script
+   ALTER TABLE rag_knowledge_base ENABLE ROW LEVEL SECURITY;
+   ```
+
+### Data Privacy
+
+- **Audit Logging**: Track all knowledge operations
+- **Data Retention**: Implement data cleanup policies
+- **User Consent**: Add privacy controls for user data
+- **Encryption**: Use HTTPS and encrypt sensitive data
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**1. "RAG system not initialized" error**
+```bash
+# Check environment variables
+cat .env.local | grep -E "(SUPABASE|OPENAI)"
+
+# Re-run setup
+npm run setup:rag
+```
+
+**2. Empty search results**
+```bash
+# Check if knowledge base has data
+npm run seed:knowledge
+
+# Verify embeddings are generated
+# Check Supabase dashboard → rag_knowledge_base table
+```
+
+**3. Slow response times**
+```typescript
+// Adjust configuration for better performance
+const ragConfig = {
+  retrieval: {
+    topK: 5, // Reduce from default 8
+    confidenceThreshold: 0.8 // Increase for more precise results
+  }
+}
+```
+
+**4. Build errors**
+```bash
+# Clear Next.js cache
+rm -rf .next
+
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+
+# Regenerate types
+npm run db:types
+```
+
+### Getting Help
+
+1. **Check the logs**:
+   - Browser console for client errors
+   - Terminal for server errors
+   - Supabase logs for database issues
+
+2. **Debug mode**:
+   ```env
+   # .env.local
+   NODE_ENV=development
+   DEBUG=rag:*
+   ```
+
+3. **Community support**:
+   - GitHub Issues
+   - Discord community
+   - Stack Overflow with `rag-system` tag
+
+## 🎯 Next Steps
+
+Now that your AI knowledge platform is running:
+
+1. **Add Your Content**: Import your existing documentation, FAQs, and knowledge
+2. **Customize the UI**: Match your brand and user experience needs
+3. **Monitor Usage**: Use built-in analytics to understand user behavior
+4. **Optimize Performance**: Tune RAG parameters based on your content
+5. **Scale Up**: Consider production deployment and advanced features
+
+### Advanced Features to Explore
+
+- **Multi-language Support**: Configure for international users
+- **Knowledge Versioning**: Track changes and maintain history
+- **Advanced Analytics**: Implement custom tracking and insights
+- **API Integration**: Connect with existing systems
+- **Mobile App**: Deploy the companion React Native app
+
+Happy building! 🚀