🐉 Dragonroll

A comprehensive D&D campaign management platform for Dungeon Masters

Dragonroll is a powerful web application designed to streamline campaign preparation and enhance your D&D gaming experience. Generate AI-powered NPCs, manage campaigns, and access a suite of tools to make your DM life easier.

🎯 Mission

Dragonroll empowers Dungeon Masters of all experience levels with intelligent tools to create compelling campaigns. By leveraging AI assistance and intuitive design, we reduce preparation time while enhancing creative possibilities, making it easier than ever to run memorable D&D sessions.

🚀 Tech Stack

Frontend:

• ⚛️ React + TypeScript + Vite
• 🎨 Tailwind CSS + ShadCN/UI components
• 🔐 Firebase Authentication
• 📱 Responsive design with dark/light mode

Backend:

• 🔥 Hono API framework (Node.js)
• 🗄️ PostgreSQL with Drizzle ORM
• 🤖 OpenAI GPT-4 & DALL-E integration
• 🔑 Firebase Admin SDK for auth

Infrastructure:

• 🏠 Local Development: Embedded PostgreSQL + Firebase emulator
• 🌐 Production: Cloudflare Workers + Pages
• 📊 Database: Supabase PostgreSQL (production) / Embedded PG (local)
• 🔧 Package Management: pnpm workspace

✨ Current Features

🧙‍♂️ NPC Generator

• 🤖 AI-Powered Creation: Generate detailed NPCs using OpenAI GPT-4
• 🎨 Character Images: Automatic character portraits with DALL-E 3
• 💾 Personal Collection: Save and organize your generated NPCs
• 📝 Custom Prompts: Tailor generation with specific requirements
• 🔒 Secure Storage: User-specific collections with Firebase authentication
• 🎭 Rich Details: Names, descriptions, backgrounds, and motivations

🎯 Planned Features (Coming Soon)

• 🗺️ Map Generator: AI-powered dungeon and world maps
• ⚔️ Encounter Builder: Balanced combat encounters
• 💰 Loot Generator: Treasure and magic item creation
• 📖 Story Prompts: Campaign and plot hook generators
• 🏰 Campaign Hub: Centralized campaign management

⚠️ Important: NPC Generator requires an OpenAI API key. Add OPENAI_API_KEY=your_key_here to your server/.env file.

🛠️ Development Setup

Prerequisites

• Node.js 20+
• pnpm 8+ (npm install -g pnpm)
• OpenAI API Key (for NPC generation)

Quick Start

1. Clone and install dependencies:

git clone https://github.com/yourusername/dragonroll.git
cd dragonroll
pnpm install

2. Set up environment variables:

# Copy template and add your OpenAI API key
cp server/.env.template server/.env
# Edit server/.env and add: OPENAI_API_KEY=your_key_here

3. Start development servers:

pnpm run dev

This starts:

• Frontend: http://localhost:5173 (or next available)
• Backend API: http://localhost:8787 (or next available)
• PostgreSQL: Embedded database (dynamic port from 5433)
• Firebase Emulator: Authentication emulator

Individual Commands

# Frontend only
cd ui && pnpm dev

# Backend only  
cd server && pnpm dev

# Build for production
pnpm run build

# Run tests
cd server && pnpm test

Testing the Application

1. Access the app at http://localhost:5173
2. Sign in with any email/password (Firebase emulator mode)
3. Generate NPCs - Go to the NPC Generator page
4. Test API directly:

curl http://localhost:8787/api/v1/hello

🔗 Connecting Production Services

Your app defaults to everything running locally. Connect to production services when you're ready:

Connect Production Database

# Choose from available providers
pnpm connect:database

# Or connect to specific provider
pnpm connect:database:neon      # Neon PostgreSQL
pnpm connect:database:supabase  # Supabase PostgreSQL
pnpm connect:database:custom    # Custom PostgreSQL

Connect Production Authentication

# Set up production Firebase Auth
pnpm connect:auth

Connect Production Deployment

# Set up Cloudflare Workers + Pages deployment
pnpm connect:deploy

Check Connection Status

# See what's connected to production vs local
pnpm connection:status

What happens when you connect services:

• Your .env files are automatically updated
• A backup of your current config is created
• You can always revert to local development by restoring the backup

📁 Project Structure

dragonroll/
├── ui/                    # React frontend (Vite + TypeScript)
│   ├── src/
│   │   ├── components/    # ShadCN/UI components + custom components
│   │   │   ├── ui/       # Base ShadCN components
│   │   │   └── npc-generator.tsx # NPC generation component
│   │   ├── pages/        # Application pages/routes
│   │   │   └── NPCGenerator.tsx # Main NPC generator page
│   │   ├── lib/          # Utilities, Firebase config, API communication
│   │   ├── types/        # TypeScript type definitions
│   │   └── hooks/        # React custom hooks
│   └── package.json
├── server/               # Hono API backend
│   ├── src/
│   │   ├── controllers/  # API route controllers
│   │   │   └── npcs.ts   # NPC-related endpoints
│   │   ├── lib/          # Server utilities
│   │   │   ├── openai.ts # OpenAI integration
│   │   │   ├── db.ts     # Database connection
│   │   │   └── env.ts    # Environment configuration
│   │   ├── middleware/   # Auth & other middleware
│   │   ├── schema/       # Database schema (Drizzle ORM)
│   │   │   ├── users.ts  # User table schema
│   │   │   └── npcs.ts   # NPC table schema
│   │   └── api.ts        # API routes & server setup
│   ├── drizzle/          # Database migrations
│   ├── .env              # Environment variables (create from template)
│   └── package.json
├── database-server/      # Embedded PostgreSQL for local development
├── data/                 # Local development data (auto-generated)
│   ├── postgres/         # PostgreSQL data files
│   └── firebase-emulator/ # Firebase emulator data (auto-backed up)
├── docs/                 # Documentation
│   ├── PRODUCT_BRIEF.md  # Project overview and goals
│   └── features/         # Feature documentation and planning
└── scripts/              # Development and utility scripts
    ├── run-dev.js        # Development server orchestration
    └── periodic-emulator-backup.js # Auto-backup Firebase data

🔧 Customization

Adding API Routes

Edit server/src/index.ts:

// Add to the existing api router
api.get('/your-route', (c) => {
  return c.json({ message: 'Hello!' });
});

// For protected routes, add to protectedRoutes:
protectedRoutes.get('/private-route', (c) => {
  const user = c.get('user'); // Get authenticated user
  return c.json({ user });
});

Database Changes

1. Edit schema in server/src/schema/
2. Push changes: cd server && pnpm db:push

UI Components

• Add components in ui/src/components/
• Use ShadCN/UI: Browse components at ui.shadcn.com
• Install new components: cd ui && npx shadcn-ui@latest add [component]

Styling

• Modify ui/tailwind.config.js for custom themes
• Global styles in ui/src/index.css
• Use Tailwind utility classes throughout

🚀 Deployment

Note: Embedded PostgreSQL is for local development only. Production deployments require an external database (configured during setup).

Backend (Cloudflare Workers)

cd server
pnpm run deploy

Your API will be available at: https://your-worker-name.your-subdomain.workers.dev

Frontend (Cloudflare Pages)

1. Connect to Git: Link your repository to Cloudflare Pages
2. Build Settings:
   • Build command: pnpm run build
   • Build output: ui/dist
3. Deploy: Automatic on every git push

Environment Variables (Production)

Set these in Cloudflare dashboards:

Worker Environment Variables:

• DATABASE_URL - Your database connection string
• FIREBASE_PROJECT_ID - Firebase project ID
• OPENAI_API_KEY - OpenAI API key for NPC generation (required for AI features)

Pages Environment Variables (if needed):

• VITE_API_URL - Your deployed worker URL (optional, defaults work)

Post-Deployment Setup

1. Update Firebase authorized domains:

   • Go to Firebase Console > Authentication > Settings
   • Add your Pages domain (e.g., your-app.pages.dev)

2. Test your deployment:

   curl https://your-worker-name.your-subdomain.workers.dev/api/v1/hello

🔐 Authentication Flow

Your app includes a complete authentication system that works in both local and production modes:

Local Mode (Default)

1. Sign in: Use any email/password combination in the UI
2. Storage: User data stored in local Firebase emulator
3. API calls: Authenticated requests work normally
4. Development: No external accounts needed

Production Mode (After pnpm connect:auth)

1. Login: Users sign in with Google (or other configured providers)
2. Token: Frontend gets Firebase ID token
3. API calls: Token sent in Authorization: Bearer <token> header
4. Verification: Backend verifies token and creates/finds user in database
5. Protection: Protected routes automatically have user context

Example API Call

// Frontend (already implemented in lib/serverComm.ts)
const response = await api.getCurrentUser();
console.log(response.user);

🗄️ Database

Your database is set up with Drizzle ORM and works the same whether local or production:

User Schema (included)

// server/src/schema/users.ts
export const users = pgTable('users', {
  id: text('id').primaryKey(),
  email: text('email').unique().notNull(),
  display_name: text('display_name'),
  photo_url: text('photo_url'),
  created_at: timestamp('created_at').defaultNow(),
  updated_at: timestamp('updated_at').defaultNow(),
});

Adding New Tables

1. Create schema file in server/src/schema/
2. Export from main schema file
3. Push to database: cd server && pnpm db:push

📚 Learning Resources

• React: react.dev
• Hono: hono.dev
• Drizzle ORM: orm.drizzle.team
• Tailwind CSS: tailwindcss.com
• ShadCN/UI: ui.shadcn.com
• Cloudflare Workers: developers.cloudflare.com/workers
• Firebase Auth: firebase.google.com/docs/auth

🆘 Troubleshooting

Development Issues

Backend won't start:

cd server
# Check environment variables
cat .env
# Reinstall dependencies
pnpm install

Database connection errors:

cd server
# Test database connection
pnpm db:push

Frontend build errors:

cd ui
# Clear cache and reinstall
rm -rf node_modules .vite dist
pnpm install

Authentication Issues

Local Development:

• Firebase emulator should start automatically with pnpm dev
• Try signing in with any email/password combination
• Check data/firebase-emulator/ for persisted data
• Data Protection: Emulator data is automatically backed up every 60 seconds and on clean shutdown to prevent data loss during crashes

Production Mode:

1. Check Firebase config: ui/src/lib/firebase-config.json
2. Verify environment variables: server/.env
3. Check authorized domains in Firebase Console

Deployment Issues

1. Verify build succeeds locally
2. Check environment variables in Cloudflare dashboards
3. Review logs in Cloudflare Workers/Pages dashboards

🎯 Next Steps

1. Explore the code: Start with ui/src/App.tsx and server/src/index.ts
2. Customize the UI: Modify components and styling
3. Add features: Build your app logic in both frontend and backend
4. Deploy: Push to git for automatic deployment

---

Happy coding! 🚀

Need help? Check the detailed documentation in each workspace (server/README.md, ui/README.md) or visit the community discussions.