An intelligent study assistant built on Cloudflare's edge infrastructure, powered by Llama 3.3 through Workers AI, featuring real-time chat, persistent memory, and WebSocket communication.
🔗 Live Demo: cf-ai-study-assistant.pages.dev
- Features
- Architecture
- Quick Start
- API Documentation
- Configuration
- Testing
- Deployment
- Troubleshooting
- Resources
- AI-Powered Chat: Leverages Llama 3.3 for intelligent, context-aware responses
- Persistent Memory: Durable Objects store conversation history across sessions
- Real-time Communication: WebSocket support for instant chat experience
- Search Functionality: Find specific topics in your chat history
- Global Performance: Deployed on Cloudflare Workers for ultra-low latency
- Stateful Sessions: Each user gets their own isolated study session
- Responsive UI: Beautiful, mobile-friendly interface
Backend:
- ⚡ Cloudflare Workers - Serverless compute at the edge
- 🔄 Durable Objects - Stateful sessions with SQLite persistence
- 🤖 Workers AI - Llama 3.3 70B model
- 🔌 WebSockets - Real-time bidirectional communication
Frontend:
- 🎨 Vanilla JavaScript - Lightweight, fast-loading UI
- 📱 Responsive CSS3 - Mobile-first design
- 🌐 Cloudflare Pages - Static site hosting with global CDN
cf-ai-study-assistant/
├── worker/
│ ├── index.js # Main Worker entry point & router
│ └── study-agent.js # Durable Object with AI logic
├── frontend/
│ ├── index.html # Chat interface
│ ├── styles.css # Styling & animations
│ └── app.js # Frontend logic & WebSocket
├── wrangler.toml # Cloudflare configuration
├── package.json # Dependencies
├── README.md # This file
├── ARCHITECTURE.md # Technical deep-dive
├── TESTING.md # Testing guide
├── PROMPTS.md # Development journey & AI prompts
├── CONTRIBUTING.md # Contribution guidelines
└── LICENSE # MIT License
- Node.js (v16 or higher)
- Cloudflare Account (free tier works!)
- Wrangler CLI installed globally:
npm install -g wrangler
# 1. Clone the repository
git clone https://github.com/gunnarwrld/cf_ai_study_assistant.git
cd cf_ai_study_assistant
# 2. Install dependencies
npm install
# 3. Authenticate with Cloudflare
wrangler login
# 4. Start local development
npm run devYour Worker is now running at http://localhost:8787 ���
# Test health endpoint
curl http://localhost:8787/health
# Send a chat message
curl -X POST http://localhost:8787/api/chat?sessionId=test123 \
-H "Content-Type: application/json" \
-d '{"message": "Explain photosynthesis"}'
# Get chat history
curl http://localhost:8787/api/history?sessionId=test123
# Search chat history
curl "http://localhost:8787/api/search?sessionId=test123&q=photosynthesis"
# Clear history
curl -X DELETE http://localhost:8787/api/history?sessionId=test123Open frontend/index.html in your browser, or use a local server:
cd frontend
npx serve .Make sure WORKER_URL in frontend/app.js points to http://localhost:8787/ for local testing.
| Endpoint | Method | Description | Parameters |
|---|---|---|---|
/health |
GET | Health check | None |
/api/chat |
POST | Send a chat message | sessionId, message (body) |
/api/history |
GET | Get chat history | sessionId, limit (opt) |
/api/history |
DELETE | Clear chat history | sessionId |
/api/search?q=query |
GET | Search chat history | sessionId, q |
Connection URL:
wss://YOUR_WORKER_URL/api/chat?sessionId=YOUR_SESSION_ID
Message Types:
// Send a chat message
{
"type": "chat",
"message": "Your question here"
}
// Get history
{
"type": "getHistory",
"limit": 20
}
// Search
{
"type": "search",
"query": "search term"
}Response Format:
{
"response": "AI response here",
"timestamp": 1704888888888
}name = "cf-ai-study-assistant"
main = "worker/index.js"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
# Durable Objects binding
[[durable_objects.bindings]]
name = "STUDY_AGENT"
class_name = "StudyAgent"
script_name = "cf-ai-study-assistant"
# Durable Object migrations
[[migrations]]
tag = "v1"
new_sqlite_classes = ["StudyAgent"]
# Workers AI binding
[ai]
binding = "AI"Edit worker/study-agent.js:
const response = await this.env.AI.run(
"@cf/meta/llama-3.3-70b-instruct-fp8-fast",
{
messages: conversationHistory,
max_tokens: 1024, // Adjust response length
temperature: 0.7, // Adjust creativity (0.0-1.0)
// Alternative models:
// '@cf/meta/llama-3.1-8b-instruct'
// '@cf/mistral/mistral-7b-instruct-v0.1'
}
);Create .dev.vars for local development:
MAX_HISTORY_MESSAGES=50
AI_TEMPERATURE=0.7
AI_MAX_TOKENS=1024# Start dev server
npm run dev
# Test all endpoints
npm test # (if test scripts are configured)- Health endpoint responds:
/health - Chat messages receive AI responses
- Response time < 3 seconds
- Chat history persists across sessions
- Search finds relevant messages
- Clear history resets conversation
- WebSocket connection works
- Frontend UI is responsive
For detailed testing procedures, see TESTING.md.
npm run deployThis outputs your Worker URL: https://cf-ai-study-assistant.YOUR_SUBDOMAIN.workers.dev
Option A: Via Wrangler
# Update WORKER_URL in frontend/app.js first
npm run pages:deployOption B: Via Dashboard
- Go to Cloudflare Dashboard → Pages
- Create a new project
- Upload the
frontend/folder - Deploy!
Don't forget: Update WORKER_URL in frontend/app.js to your production Worker URL and use wss:// for WebSocket connections.
- Ensure your Worker URL supports WebSocket upgrades
- Check browser console for connection errors
- Verify CORS settings in
worker/index.js - Use
wss://(notws://) in production
- Confirm migrations are applied in
wrangler.toml - Ensure proper binding name:
STUDY_AGENT - Check Durable Objects are enabled in your Cloudflare account
- Verify
new_sqlite_classesmigration for free tier compatibility
- Verify AI binding in
wrangler.toml - Check model name is correct:
@cf/meta/llama-3.3-70b-instruct-fp8-fast - Ensure Workers AI is enabled for your account
- Check rate limits: 30 requests/min on free tier
- Run
wrangler whoamito verify authentication - Check account has Workers and Durable Objects enabled
- Ensure you have a workers.dev subdomain configured
- Review Cloudflare dashboard for error logs
- Global Edge Network: Deployed to 300+ locations worldwide
- Low Latency: Average response time < 50ms
- Auto-scaling: Handles traffic spikes automatically
- Stateful Sessions: Durable Objects ensure consistency
- 100,000 Worker requests/day
- 1,000 Durable Object requests/day
- 30 Workers AI requests/min
- SQLite storage included with Durable Objects
- Session Isolation: Each user session is isolated in its own Durable Object
- Data Persistence: Chat history stored securely in Durable Object SQLite storage
- CORS: Configured for cross-origin requests
- No External Data Sharing: All data stays within your Cloudflare account
- Input Validation: Sanitized user input to prevent injection attacks
- ARCHITECTURE.md - Technical architecture deep-dive
- TESTING.md - Testing guide & development workflow
- PROMPTS.md - AI prompts used during development
- CONTRIBUTING.md - How to contribute
Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation
See CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
This AI-powered study assistant was built as a learning project to demonstrate:
- Modern serverless architecture on Cloudflare's edge platform
- Real-time communication with WebSockets
- Stateful session management with Durable Objects
- AI integration using Workers AI (Llama 3.3)
- Full-stack development without traditional servers
Built by: gunnarwrld
Built with ❤️ using Cloudflare's edge platform
⭐ If you found this helpful, consider starring the repo!