the-sunken-reach/README.md

The Sunken Reach — D&D 5e Campaign Manager

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 character panel on every page, weapons/inventory/spells, monsters, and a real-time encounter/combat tracker.

How it works

/docs describes the app as it currently behaves, one subject per file:

Document	Covers
docs/CHARACTERS.md	Building a character, every number on the sheet, levels, money, permissions
docs/WEAPONS.md	The weapon pool and library, equipping, weapon levels and how damage grows
docs/SPELLS.md	The spell list, who can use which spells, the spell library
docs/ITEMS.md	The item pool and library, armor and other gear effects, what can be equipped, items for sale
docs/ENCOUNTERS.md	Battles and NPC quests, turns, rewards, trade, what players see
docs/MONSTERS.md	The monster list and built-in bestiary
docs/NPCS.md	Non-player characters, what they sell and the rates they change money at
docs/SEEDS.md	World seeds: ready-made campaigns a DM starts from a code, and how to add one

CLAUDE_BUILD_PROMPT.md, docs/GAME_RULES_REFERENCE.md and docs/ROLL_YOUR_CHARACTER.md are the original specifications the first version was built from. The app has since moved on in places (gear levels, the builder's story steps, picking a motivation); the documents above are the current behaviour.

Getting around

The same four destinations are always on screen: Campaigns (the list), Campaign and Party (for the campaign you were last in, from any page, including a character sheet or an encounter) and Account.

• On a wide screen they are links along the top bar, and the dice roller floats at the bottom left.
• On a phone or small tablet (900px wide or less) they are a bar along the bottom of the screen, with the dice roller as its last button. Nothing floats over the page: the 🧙 character button sits in the top bar.
• The 🧙 character button is on every page (floating at the bottom right on a wide screen). It opens a panel with your character's numbers and everything they hold; the DM can open it for any character.
• The campaign page and the character sheet are long, so each starts with a row of section links (Characters, Encounters, NPCs, Monsters...) that jump straight to that part of the page.
• On a small screen every table (weapons, items, spells, monsters, the party overview) is shown as a stack of cards, one per row, with each figure labelled, and rows of controls wrap rather than run off the side.

Stack

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

Prerequisites

• Node.js 20.19+ (tested on Node 24)
• 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 generate       # migrate no longer does this itself
npx prisma db seed        # adds the admin account if it is missing (see output for the login and the world codes)

# 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 admin account — see the seed script's console output for the credentials), and start playing.

The database seed creates the admin account and nothing else. It only adds: an existing account, and its password, is left alone, so it is safe to run on a server with real data. SEED_ADMIN_EMAIL, SEED_ADMIN_PASSWORD and SEED_ADMIN_NAME set the account it creates. npx prisma db seed -- --reset wipes every user and campaign first.

Worlds

Campaigns are created in the app: blank, or from a world seed by its code. On the Campaigns page click "+ New Campaign" and enter a code under "Or start from a ready-made world"; the whole world is built for you as its DM.

Code	World
ALDENF	Aldenfell
HOLLOW	Hollowcrown: The Rift Between Worlds

Each world is one file in /backend/seeds. Drop another file in and its code works straight away, with no restart; npm run seeds:check (from the repo root or backend) checks every file and says what is wrong with one. docs/SEEDS.md has the format.

On a server, after pulling a new version, run npm install in the repo root (when dependencies changed) and then npm run deploy in backend and then restart the backend. It applies new migrations and regenerates the Prisma client; without the second half the server keeps running with the old data model and pages that use anything new fail to load (for example "Could not load this encounter"). Change your password from the account page ("Account" in the navigation).

Tests

cd backend
npm test

The calculation engine (src/game/calculations.js) and the world seeds (src/seeds, which also checks every file in /backend/seeds) are unit tested and run 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.config.js — where the Prisma CLI finds the schema, the database and the seed
  /prisma   — schema.prisma, migrations, seed.js (the admin account only)
  /seeds    — world seeds: one file per ready-made campaign, created by code
  /seed-data — reference JSON (species/classes/skills/weapons, 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
    /seeds      — finds, checks and creates campaigns from the world seeds
    /sockets    — Socket.io room wiring
/frontend   — React + Vite + TypeScript app
/docs       — game rules & character-builder specs (reference material)