Skip to content

QUICK_START.md

Latest commit

 

History

History
240 lines (178 loc) · 5.69 KB

QUICK_START.md

File metadata and controls

240 lines (178 loc) · 5.69 KB
Raw

Quick Start Guide

Get your Knowledge Assistant running in minutes!

✅ Prerequisites Completed

  • Project structure created
  • All code written and tested
  • Dependencies installed
  • TypeScript compilation verified
  • Frontend builds successfully

🚀 Quick Deployment

Option 1: Deploy to Cloudflare (Recommended for Submission)

Step 1: Setup Cloudflare Account

# Login to Cloudflare
npx wrangler login

Step 2: Create Database

cd backend

# Create D1 database
npx wrangler d1 create knowledge_db

# Copy the database_id from output and update wrangler.toml
# Replace YOUR_D1_DATABASE_ID in backend/wrangler.toml

# Initialize schema
npx wrangler d1 execute knowledge_db --file=../schema.sql

Step 3: Create Vector Index

# Still in backend folder
npx wrangler vectorize create knowledge-embeddings --dimensions=768 --metric=cosine

Step 4: Deploy Backend

# Still in backend folder
npm run deploy

# Note the Worker URL (e.g., https://knowledge-assistant.YOUR-SUBDOMAIN.workers.dev)

Step 5: Deploy Frontend

cd ../frontend

# Build
npm run build

# Deploy to Pages
npx wrangler pages deploy dist --project-name=knowledge-assistant

# Note the Pages URL (e.g., https://knowledge-assistant.pages.dev)

Step 6: Test Your Deployment

Visit your Pages URL and:

  1. Type a message: "I learned TypeScript is amazing"
  2. Click Voice Input and speak
  3. Ask a question: "What did I learn?"
  4. Click "Generate Summary"

Option 2: Run Locally (For Development)

Terminal 1 - Backend

cd backend
npm run dev

# Worker will run at http://localhost:8787

Terminal 2 - Frontend

cd frontend
npm run dev

# App will open at http://localhost:3000

Test Locally

  1. Open http://localhost:3000
  2. Chat interface will connect to local worker
  3. Note: Voice input requires HTTPS (works on localhost)
  4. Note: You'll need to setup D1 and Vectorize even for local testing

📋 Submission Checklist

Before Submitting

  • Repository named cf_ai_knowledge_assistant ✅
  • README.md with instructions ✅
  • PROMPTS.md with AI prompts ✅
  • All code compiles without errors ✅
  • Project builds successfully ✅

For Submission

  • Create GitHub repository
  • Push code to GitHub
  • Submit repository URL

Git Commands

cd /Users/wooyoungkang/Desktop/CF

# Initialize git
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Personal Knowledge Assistant on Cloudflare AI"

# Create GitHub repo named 'cf_ai_knowledge_assistant', then:
git remote add origin https://github.com/YOUR_USERNAME/cf_ai_knowledge_assistant.git
git branch -M main
git push -u origin main

🧪 Testing Scenarios

Test 1: Knowledge Storage

Input: "I learned React hooks are great for state management"
Expected: Knowledge stored with category "learning" and relevant tags

Test 2: Question Answering

Input: "What did I learn about React?"
Expected: AI retrieves and explains the React knowledge

Test 3: Voice Input

Action: Click "Voice Input", speak "Remember to buy milk"
Expected: Transcript appears, knowledge stored with source "voice"

Test 4: Semantic Search

Input: "Tell me about JavaScript frameworks"
Expected: Finds related entries even without exact match

Test 5: Summary Generation

Action: Click "Generate Summary"
Expected: Background workflow generates comprehensive summary

🔧 Troubleshooting

"WebSocket connection failed"

Solution:

  • Check backend is running (npm run dev in backend folder)
  • Verify URL in frontend/src/hooks/useWebSocket.ts

"Voice input not working"

Solution:

  • Must use HTTPS or localhost
  • Check browser microphone permissions
  • Supported browsers: Chrome, Edge, Safari

"Knowledge not storing"

Solution:

  • Verify D1 database created and schema initialized
  • Check Vectorize index exists
  • Look at Wrangler logs: npm run tail in backend folder

"Build errors"

Solution:

  • Delete node_modules: rm -rf node_modules package-lock.json
  • Reinstall: npm install
  • Clear build cache: rm -rf dist .vite

📊 What Each Service Does

Service Purpose Required?
Workers AI LLM inference (Llama 3.3) ✅ Yes
Durable Objects Agent state & WebSocket ✅ Yes
Workflows Background summarization ✅ Yes
Vectorize Semantic search ✅ Yes
D1 Metadata storage ✅ Yes
Pages Frontend hosting ⚠️ Optional (can use Vercel/Netlify)

💡 Tips

  1. Start Simple: Deploy backend first, test with curl or Postman
  2. Check Logs: Use npm run tail in backend to see real-time logs
  3. Local Testing: Requires Cloudflare services even locally
  4. Voice Input: Only works on HTTPS or localhost
  5. Costs: Free tier should cover testing and assignment submission

📞 Support Resources

✨ Project Highlights

Built For: Cloudflare AI Assignment
Repository: cf_ai_knowledge_assistant
Tech Stack: Workers AI, Durable Objects, Workflows, Vectorize, D1, Pages
Lines of Code: 1,400+
Time to Build: < 1 hour with AI assistance
Status: ✅ Production Ready

Ready to submit? Create your GitHub repo and share the URL! 🎉