Quick Start Guide

Get PadawanForge running in 5 minutes with this streamlined setup guide.

Prerequisites

5-Minute Setup

1. Clone and Install

git clone https://github.com/your-org/PadawanForge.git
cd PadawanForge
bun install

2. Database Setup

# Create database
bun wrangler d1 create padawan-db

# Copy the database_id from output and update wrangler.jsonc
# Look for the line: database_id = "your-id-here"

# Run migrations
bun run db:migrate

3. Environment Configuration

# Create environment file
echo 'API_TOKEN=dev-token-123' > .dev.vars
echo 'APP_NAME=PadawanForge' >> .dev.vars

4. Start Development

bun run dev

Visit http://localhost:4321 - you’re ready to go!

First Steps

Try the Demo

  1. Go to http://localhost:4321/demo
  2. Wait for AI to generate 40 History questions (30-60 seconds)
  3. Complete the 7-minute cognitive training session
  4. Review your results and achievements

Test Core Features

# Test AI integration
curl http://localhost:4321/api/ai/test-connection

# Test database
curl http://localhost:4321/api/health

# Run comprehensive tests
bun run test:all

Add Authentication (Optional)

Google OAuth Setup

  1. Visit Google Cloud Console
  2. Create a new project or select existing
  3. Enable the Google+ API
  4. Create OAuth 2.0 credentials
  5. Add redirect URI: http://localhost:4321/api/auth/callback/google
  6. Add credentials to .dev.vars:
echo 'OAUTH_GOOGLE_CLIENT_ID=your-client-id' >> .dev.vars
echo 'OAUTH_GOOGLE_CLIENT_SECRET=your-client-secret' >> .dev.vars

Discord OAuth Setup

  1. Visit Discord Developer Portal
  2. Create a new application
  3. Go to OAuth2 section and add redirect URI: http://localhost:4321/api/auth/callback/discord
  4. Add credentials to .dev.vars:
echo 'OAUTH_DISCORD_CLIENT_ID=your-client-id' >> .dev.vars
echo 'OAUTH_DISCORD_CLIENT_SECRET=your-client-secret' >> .dev.vars

Test Authentication

Visit http://localhost:4321/login and try signing in with your configured providers.

Essential Commands

Development

bun run dev          # Start development server
bun run build        # Build for production
bun run preview      # Preview production build

Database

bun run db:migrate            # Run migrations locally
bun run db:migrate:remote     # Run migrations on remote

Testing

bun run test:all             # Run all tests
bun run test:all:prod        # Test production environment

Deployment

bun run deploy              # Deploy to Cloudflare Workers
bun run check               # Dry run deployment check

Explore the Platform

Game Features

  • Demo Mode: Anonymous 7-minute cognitive training sessions
  • AI Statements: Automatically generated true/false questions
  • Streak System: Hot/cold streaks with score multipliers
  • Virtual Tutors: AI personalities (Einstein, Curie, Confucius, Sherlock)
  • Progress Tracking: XP, levels, and achievement system

Administrative Tools

  • Player Management: View and manage registered players
  • NPC Configuration: Customize AI tutor personalities
  • Analytics Dashboard: Performance metrics and insights
  • Role System: Granular permissions (Guest, Padawan, Game Master, etc.)

Technical Features

  • Edge Performance: Cloudflare Workers for global low latency
  • Real-time Chat: WebSocket-based messaging system
  • AI Integration: Cloudflare Workers AI for content generation
  • Privacy Controls: Granular data visibility settings

Key URLs

Main Application

Administrative

Documentation

API Endpoints

Common Tasks

Create a Demo Session

curl -X POST http://localhost:4321/api/demo/session \
  -H "Content-Type: application/json" \
  -d '{}'

Generate AI Statements

curl -X POST http://localhost:4321/api/ai/generate-statements \
  -H "Content-Type: application/json" \
  -d '{"topic": "Science", "difficulty": "basic", "count": 10}'

Check Player Stats

curl http://localhost:4321/api/users/stats

Troubleshooting

Development Server Won’t Start

# Check if port 4321 is in use
lsof -i :4321

# Kill any processes using the port
kill -9 $(lsof -t -i:4321)

# Restart development server
bun run dev

Database Issues

# Verify database exists
bun wrangler d1 list

# Check migrations
bun wrangler d1 execute padawan-db --local --command="SELECT name FROM sqlite_master WHERE type='table';"

# Reset database (if needed)
bun run db:migrate

AI Generation Not Working

# Test AI connection
curl http://localhost:4321/api/ai/test-connection

# Check Cloudflare Workers logs
bun wrangler tail

OAuth Errors

  1. Verify redirect URIs match exactly in provider settings
  2. Check client IDs and secrets in .dev.vars
  3. Ensure provider applications are properly configured

Production Deployment

Quick Production Setup

# Create production database
bun wrangler d1 create padawan-db-prod

# Update wrangler.jsonc with production database ID

# Run remote migrations
bun run db:migrate:remote

# Set production secrets
bun wrangler secret put API_TOKEN
bun wrangler secret put OAUTH_GOOGLE_CLIENT_ID
bun wrangler secret put OAUTH_GOOGLE_CLIENT_SECRET

# Deploy
bun run deploy

# Test production
bun run test:all:prod

Custom Domain Setup

# Add custom domain
bun wrangler custom-domains create your-domain.com

# Update OAuth redirect URIs to use your domain
# Update any hardcoded localhost references

Next Steps

Learn More

Customize Your Instance

Contribute

Support

Getting Help

  • Documentation: Comprehensive guides in the /docs directory
  • GitHub Issues: Report bugs and request features
  • Community Discussions: Connect with other developers
  • Developer Chat: Real-time support in Discord/Slack

Common Resources

You’re now ready to start building with PadawanForge! The platform provides a solid foundation for cognitive training games with modern web technologies and edge computing performance.

Configuration Guide →
PadawanForge v1.4.1