A web app for a D&D 5e Dungeon Master and their players to run a campaign together: campaign management, a guided dice-roll character builder, live character sheets, a mid-combat "quick stats" panel, weapons/inventory/spells, monsters, and a real-time encounter/combat tracker.

See CLAUDE_BUILD_PROMPT.md and /docs for the full spec this was built from (GAME_RULES_REFERENCE.md is the authoritative rules/math reference; ROLL_YOUR_CHARACTER.md is the character-builder flow spec).

Stack

Backend: Node.js + Express, JavaScript, Prisma ORM, PostgreSQL, Socket.io, JWT auth (bcrypt + jsonwebtoken), zod validation.
Frontend: React + Vite + TypeScript, React Router, TanStack Query, socket.io-client.

Prerequisites

Node.js 18+ (tested on Node 22)
A running PostgreSQL instance (local install, Docker, or a hosted service like Neon/Supabase)

First-time setup

npm install   # installs both workspaces (backend + frontend)

# Backend: point at your Postgres instance and run migrations
cd backend
cp .env.example .env      # edit DATABASE_URL and JWT_SECRET
npx prisma migrate dev --name init
npx prisma db seed        # creates a demo campaign + demo users (see output for login/invite code)

# Frontend
cd ../frontend
cp .env.example .env      # defaults to http://localhost:4000, adjust if needed

Running in dev

In two terminals, from the repo root:

npm run dev:backend    # Express + Socket.io on http://localhost:4000
npm run dev:frontend   # Vite dev server, prints its own port (5173 by default)

Open the frontend URL, register an account (or log in with the seeded demo users — see the seed script's console output for credentials and invite code), and start playing.

Tests

cd backend
npm test

The calculation engine (src/game/calculations.js) is fully unit tested and runs with no external dependencies. The route-level integration tests in src/routes/api.integration.test.js need a real, migrated database reachable via DATABASE_URL — they skip themselves gracefully (with a console warning) if the DB isn't reachable, so npm test still passes in an environment with no database configured.

Project layout

/backend    — Express + Prisma API, Socket.io server
  /prisma   — schema.prisma, seed.js
  /seed-data — reference JSON (weapons seeded per-campaign; species/classes/skills
               are ported into src/game/data/*.js and used directly by the
               calculation engine, not stored as DB rows)
  /src
    /game       — calculations.js (the ONLY place D&D formulas live) + buildFlow.js
    /middleware — auth + campaign/character authorization
    /routes     — auth, campaigns, characters, encounters, notes
    /sockets    — Socket.io room wiring
/frontend   — React + Vite + TypeScript app
/docs       — game rules & character-builder specs (reference material)