A comprehensive web application for managing Dungeons & Dragons characters and campaigns, built with modern web technologies and deployed on Cloudflare's edge infrastructure.
- Create and customize D&D 5e characters
- Track ability scores, skills, and proficiencies
- Manage equipment, spells, and features
- Character progression and leveling
- Portrait and token uploads
- Create and organize campaigns
- Invite players and manage permissions
- Track session logs and character progression
- Share maps, handouts, and assets
- Campaign-specific settings and rules
- Responsive design for desktop and mobile
- Offline capability with service workers
- Real-time updates and collaboration
- Secure authentication and authorization
- Fast global performance via Cloudflare Edge
- React 18 with TypeScript
- Vite for fast development and building
- Tailwind CSS for styling
- Redux Toolkit for state management
- React Router for navigation
- Cloudflare Workers for serverless API
- Hono framework for request routing
- TypeScript for type safety
- Zod for input validation
- JWT for authentication
- Cloudflare D1 for SQLite database
- Cloudflare KV for caching and sessions
- Cloudflare R2 for file storage
- Cloudflare Pages for static hosting
- GitHub Actions for CI/CD
- Design System: Complete D&D-themed UI components with Radix UI + Tailwind CSS
- Components: Button, Input, Card, Badge, Dice, Dialog components
- Development Server: Running at http://localhost:3000
- Responsive Design: Mobile-first approach with touch-friendly interfaces
- Production Deployment: https://dnd-character-manager-api-dev.cybermattlee-llc.workers.dev
- Frontend Production: https://dnd.cyberlees.dev
- Authentication: JWT-based with secure session management
- Character Management: Full CRUD operations for D&D 5e characters
- Security: CORS, rate limiting, input validation, password hashing
- Database: D1 SQLite with complete D&D 5e schema (17 tables)
POST /api/auth/register- User registration ✅POST /api/auth/login- User authentication ✅POST /api/auth/logout- Session termination ✅GET /api/auth/profile- User profile ✅POST /api/auth/refresh- Token refresh ✅GET /api/characters- List characters ✅POST /api/characters- Create character ✅GET /api/characters/:id- Get character ✅PUT /api/characters/:id- Update character ✅DELETE /api/characters/:id- Delete character ✅GET /health- System health check ✅
- Character creation wizard UI
- Interactive character sheets
- Campaign management
- Real-time collaboration features
- Node.js 20 or higher
- npm package manager
- Cloudflare account (for deployment)
- Git
-
Clone the repository
git clone <repository-url> cd ddcharacterbot
-
Install dependencies
# Install API dependencies cd api && npm install # Install frontend dependencies cd ../frontend && npm install
-
Start development servers
# Terminal 1: Start frontend (from /frontend directory) npm run dev # Terminal 2: Start API (from /api directory) npm run dev
-
Access the application
- Frontend: http://localhost:3000
- API: http://localhost:8787
- Design System: http://localhost:3000/design-system
-
Install Wrangler CLI
npm install -g wrangler
-
Authenticate with Cloudflare
wrangler auth login
-
Set up database and KV
cd api # Create D1 database wrangler d1 create dnd-character-manager-dev # Create KV namespace wrangler kv namespace create "KV" wrangler kv namespace create "KV" --preview # Update wrangler.toml with generated IDs
-
Run database migrations
wrangler d1 execute DB --file=../database/migrations/0001_initial_schema.sql --env=development --remote
-
Set JWT secret
echo "your-jwt-secret-key" | wrangler secret put JWT_SECRET --env development
-
Deploy API
npm run deploy:dev
-
Start development servers
# Terminal 1: Start API cd api && npm run dev # Terminal 2: Start frontend cd frontend && npm run dev
Visit http://localhost:3000 to access the application.
dnd-character-manager/
├── api/ # Cloudflare Workers API
│ ├── src/
│ │ ├── routes/ # API route handlers
│ │ ├── lib/ # Utilities and managers
│ │ ├── middleware/ # Security and validation
│ │ └── index.ts # Main application entry
│ ├── wrangler.toml # Workers configuration
│ └── package.json
├── frontend/ # React application
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── pages/ # Page components
│ │ ├── store/ # Redux store
│ │ ├── utils/ # Utilities
│ │ └── main.tsx # Application entry
│ ├── vite.config.ts # Vite configuration
│ └── package.json
├── database/ # Database schema and migrations
│ ├── migrations/ # SQL migration files
│ └── seeds/ # Sample data
├── infrastructure/ # Environment configurations
│ ├── environments/ # Environment-specific settings
│ └── setup.sh # Infrastructure setup script
├── .github/workflows/ # CI/CD pipelines
└── docs/ # Additional documentation
cd api
# Development server
npm run dev
# Build TypeScript
npm run build
# Run tests
npm run test
# Database operations
npm run db:migrate
npm run db:seed
# Deploy
npm run deploy
npm run deploy:staging
npm run deploy:productioncd frontend
# Development server
npm run dev
# Build for production
npm run build
npm run build:staging
npm run build:production
# Preview production build
npm run preview
# Run tests
npm run test
# Linting and type checking
npm run lint
npm run type-checkCreate environment files for local development:
Frontend (frontend/.env.local):
VITE_API_URL=http://localhost:8787
VITE_ENVIRONMENT=development
VITE_FEATURE_AI_GENERATION=trueAPI (via Wrangler secrets):
wrangler secret put JWT_SECRET --env development
wrangler secret put DATABASE_ENCRYPTION_KEY --env developmentThe application uses automated deployment via GitHub Actions:
- Development: Push to
developbranch - Staging: Push to
stagingbranch - Production: Push to
mainbranch
# Deploy API
cd api && npm run deploy:production
# Deploy Frontend
cd frontend && npm run build:production
wrangler pages deploy dist --project-name dnd-character-managerFor detailed deployment instructions, see DEPLOYMENT.md.
POST /api/auth/register- User registrationPOST /api/auth/login- User loginPOST /api/auth/logout- User logoutGET /api/auth/profile- Get user profile
GET /api/characters- List user's charactersPOST /api/characters- Create new characterGET /api/characters/:id- Get character detailsPUT /api/characters/:id- Update characterDELETE /api/characters/:id- Delete character
GET /api/campaigns- List user's campaignsPOST /api/campaigns- Create new campaignGET /api/campaigns/:id- Get campaign detailsPUT /api/campaigns/:id- Update campaignDELETE /api/campaigns/:id- Delete campaign
POST /api/assets/upload- Upload character portrait/assetGET /api/assets/:id- Download assetDELETE /api/assets/:id- Delete asset
GET /health- Basic health checkGET /health/detailed- Detailed system statusGET /health/metrics- Application metrics
- JWT-based authentication with secure sessions
- Role-based access control (RBAC)
- Resource ownership validation
- Campaign membership verification
- Content Security Policy (CSP)
- CSRF protection
- Rate limiting per user/IP
- Input validation and sanitization
- Secure file upload validation
- Encrypted sensitive data storage
- Secure session management
- Privacy-compliant user data handling
- Automated data retention policies
- Global edge deployment via Cloudflare
- Intelligent caching strategies
- Asset optimization and compression
- Code splitting and lazy loading
- Service worker for offline capability
- Real-time performance metrics
- Error tracking and alerting
- Health checks and uptime monitoring
- Database query optimization
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow TypeScript best practices
- Write tests for new features
- Follow existing code style and patterns
- Update documentation for API changes
- Test in staging before production deployment
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run specific test suite
npm test -- --grep "Character Management"This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: See DEPLOYMENT.md for deployment details
- Issues: Report bugs and feature requests on GitHub Issues
- Security: Report security vulnerabilities privately to [security@example.com]
- Community: Join our Discord server for community support
- Advanced character sheet customization
- Campaign calendar and scheduling
- Enhanced mobile experience
- Character import/export features
- Real-time collaborative editing
- Voice/video integration
- Advanced campaign analytics
- Third-party integrations (Roll20, D&D Beyond)
- Multi-system support (Pathfinder, etc.)
- AI-powered character generation
- Advanced campaign management tools
- Mobile applications
Built with ❤️ using Cloudflare's edge infrastructure for global performance and reliability.