Build Prompt: D&D Campaign Manager Web App

Hand this whole folder to Claude Code (or paste this file as the initial prompt with the rest of the folder alongside it) to build the app. Read this file fully before writing any code, then read prisma/schema.prisma, docs/GAME_RULES_REFERENCE.md, and docs/ROLL_YOUR_CHARACTER.md — those three are the authoritative data model and game-logic spec, not just background.

What we're building

A web app for a Dungeons & Dragons 5e Dungeon Master and their players to run a campaign together. Users log in and see the campaigns/stories they're active in. Opening a campaign shows a player their character card (stats, spells, inventory). A DM can configure campaign basics, add characters, and build full character sheets through a guided dice-roll flow. Players can also build and manage their own characters, take notes, and pull up a contextual "quick stats" panel mid-combat (attack/damage bonus, HP, special abilities). The DM can create and assign weapons, create monsters/enemies, run encounters, and track damage live.

Tech stack (fixed — do not substitute)

Backend: Node.js + Express (or Fastify if you strongly prefer, but default to Express), JavaScript (not TypeScript, to match the stack the user works in day to day), Prisma ORM, PostgreSQL.
Frontend: React + Vite + TypeScript.
Real-time: Socket.io over WebSockets, self-hosted on the Express server — no paid real-time SaaS (no Pusher, Ably, Supabase Realtime, etc.).
Auth: Email + password. Hash passwords with bcrypt. Issue a JWT on login, store it client-side, verify it as Express middleware. A DM invites players to a campaign via a short invite code or a shareable /join/:inviteCode link (see Campaign.inviteCode in the schema).
Repo layout: monorepo, two top-level folders:

/frontend   — React + Vite + TypeScript app
/backend    — Express + Prisma API, Socket.io server
/prisma     — (already provided) schema.prisma — move into /backend/prisma
/seed-data  — (already provided) JSON reference data — move into /backend/prisma or /backend/src/data, wire into a seed script
/docs       — (already provided) keep as top-level /docs for reference during and after the build

Move prisma/ and seed-data/ into /backend as part of scaffolding (or keep top-level and point backend/prisma/schema.prisma's location via package.json's prisma.schema field — either is fine, just be consistent).

First command to run

cd backend && npx prisma validate

This schema was authored and structurally reviewed (brace/paren balance, no duplicate models/enums, relation names cross-checked by hand) but could not be run through prisma validate in the environment that generated it — its sandbox blocked outbound access to Prisma's engine-binary CDN. Run it for real as your first step before trusting the schema further.

Database & seeding

prisma migrate dev from the schema as provided (adjust only if prisma validate surfaces a real error).
Write backend/prisma/seed.js (or .ts) that reads the four JSON files in seed-data/ and:
- Does not need to load species/classes/skills into the database as rows — those are fixed game-rule tables, not user data. Instead, port them into a small constants module the calculation engine imports directly (e.g. backend/src/game/data/species.js etc., generated from the JSON so the numbers stay traceable to docs/GAME_RULES_REFERENCE.md).
- Does seed weapons.json into the Weapon table, but only as part of a demo/dev campaign seed (weapons are per-campaign in the schema, since a DM should be able to add homebrew weapons) — don't seed them globally.
Build the calculation engine described in docs/GAME_RULES_REFERENCE.md as a single module, fully unit tested (ability modifier, proficiency bonus, HP by level — including the level-1-uses-max-die rule, AC, save/skill bonuses, spell DC/attack bonus). Every place in the API that returns a character's derived stats must call this module — never duplicate the formulas.

Backend API — suggested route groups

POST /auth/register, POST /auth/login, GET /auth/me
GET /campaigns (mine, as DM or player), POST /campaigns (create, DM becomes owner), GET /campaigns/:id, PATCH /campaigns/:id (DM-only, updates startingItemCount/startingSpellCount/startingGold/etc.)
POST /campaigns/:id/invite (DM regenerates/fetches invite code), POST /campaigns/join/:inviteCode (player joins)
GET /campaigns/:id/characters, POST /campaigns/:id/characters (start a build — DM for anyone, player for themselves)
GET /characters/:id, PATCH /characters/:id (stats/notes updates), DELETE /characters/:id (DM only)
POST /characters/:id/build/roll (server-rolls the requested die for the current build step — never trust a client-submitted roll — see docs/ROLL_YOUR_CHARACTER.md), POST /characters/:id/build/choose (submit a choice for the current step), POST /characters/:id/build/finalize
GET /characters/:id/quick-stats (assembles the combat-context panel per docs/GAME_RULES_REFERENCE.md)
POST /characters/:id/weapons, PATCH /characters/:id/weapons/:weaponId (equip/unequip/quantity), weapon CRUD under /campaigns/:id/weapons (DM)
POST /characters/:id/inventory, PATCH /characters/:id/inventory/:itemId
Monster CRUD under /campaigns/:id/monsters (DM only)
POST /campaigns/:id/encounters, GET /encounters/:id, POST /encounters/:id/participants (add character/monster), PATCH /encounters/:id/participants/:participantId (HP/conditions/initiative updates — this is the hot path during combat), POST /encounters/:id/advance-round
POST /notes, GET /campaigns/:id/notes, GET /characters/:id/notes

Authorization rule of thumb: DM (campaign owner / CampaignMember.role === 'DM') can read/write everything in their campaign; a player can read their own character fully, can read other players' character cards at whatever visibility the DM allows (default: full read for party members — keep it simple for v1), and can only write to their own character and their own notes.

Real-time events (Socket.io)

Join a Socket.io room per campaign (campaign:<id>) on connect. Emit on:

Character HP/condition changes (character:updated)
Encounter participant HP/condition/initiative changes (encounter:participant-updated)
Encounter round advances (encounter:round-advanced)
New character added / build finalized (character:created)

This is what makes HP changes and combat tracking show up live for everyone looking at the same campaign/encounter — keep the payloads small (just the changed record) and let the frontend re-fetch details if needed rather than pushing full derived-stat blobs over the socket.

Frontend — key screens

Login / Register
Campaign list (post-login home) — campaigns the user is a DM or player in; a "Join campaign" flow that takes an invite code/link
Campaign home — DM sees campaign settings + character list + "start encounter"; player sees their character card front and center
Character card / sheet — stats, AC, HP (editable inline for authorized users), skills, saves, spells, inventory, weapons, notes
Character builder — walks docs/ROLL_YOUR_CHARACTER.md step by step: big "Roll d_N_" buttons, reveal choices, assign ability scores, pick skills, pick starting equipment, finalize
Quick Stats panel — a compact overlay/drawer callable from anywhere the character is on screen, showing attack/damage bonus (per equipped weapon), HP, AC, and special abilities — this is what a player pulls up mid-attack, so it must be fast to open (no full page nav) and legible at a glance
DM encounter/combat tracker — add characters and monsters to an encounter, initiative order, per-combatant HP/condition tracking, round counter, all live via Socket.io

Use React Query (or an equivalent fetch/cache layer) for API state and a lightweight Socket.io client hook that invalidates/updates the relevant query cache on each event above, rather than hand-rolling a parallel state store.

Build phases (do these in order; each should be independently runnable/testable)

Monorepo scaffold: /frontend (Vite React-TS template) + /backend (Express, npm init, Prisma installed, schema in place), root README with dev-run instructions, .env.example in both.
Prisma migrate + seed script + the calculation engine module + its unit tests (this is the foundation everything else depends on — get it fully correct and tested before building UI on top of it).
Auth (register/login/JWT middleware) + campaign CRUD + invite/join flow.
Character builder end-to-end (dice-roll flow → finalized character), backed by the calculation engine.
Character sheet view (read) + stat/note editing (write) on the frontend.
Quick Stats panel.
Weapons (campaign-level CRUD + assign to character) and inventory.
Monsters + encounters + combat/damage tracking.
Socket.io wiring for all the real-time events above.
Polish pass: loading/error states, mobile-usable layout (a DM running combat from a phone or tablet at the table is a realistic use case), basic automated tests for the calculation engine and the auth/campaign/character API routes.

Non-functional requirements

Validate all request bodies server-side (e.g. zod) — don't trust the client for anything that affects game state, especially dice rolls.
Never let a non-DM, non-owning-player mutate a character or campaign they don't have rights to — enforce this in middleware, not just by hiding UI.
Keep the calculation engine pure and dependency-free (no DB calls inside it) so it stays unit-testable in isolation.
Match the naming and structure in prisma/schema.prisma and the JSON files in seed-data/ exactly — they're the result of a full review pass and are meant to be used as-is, not redesigned.

Reference material in this folder

prisma/schema.prisma — full data model, described above
docs/GAME_RULES_REFERENCE.md — every D&D formula the app needs, verified against a hand-checked Excel calculator built earlier for this same campaign
docs/ROLL_YOUR_CHARACTER.md — the dice-roll character build flow, step by step, for the builder UI
seed-data/species.json, classes.json, skills.json, weapons.json — structured versions of the tables in GAME_RULES_REFERENCE.md, ready to import into code or a seed script

10 KiB Raw Permalink Blame History