19 KiB
AGENTS.md — Dragonroll
Orientation map, kept short on purpose. Read the file you are about to change: this tells you where to
look and what will bite you, it does not replace the code. Longer docs: dragonroll-foundry/README.md,
discord-bot/README.md, obsidian-plugin/README.md.
1. What this is
Free/open-source helper for tabletop RPG campaigns (campaigns, markdown notes, folders, characters, items, maps, dice widgets, sounds).
backend/— Node + Express 5 + Mongoose 9 (MongoDB) REST API, JWT auth, CommonJS, entrysrc/index.js.frontend/— Nuxt 4 / Vue 3 (<script setup>), SCSS, axios, marked, mitt, motion, entryapp/app.vue. No routed pages (§5.1).discord-bot/— Discord bot (slash commands) that talks to the backend with a shared service secret, no login.dragonroll-foundry/— Foundry VTT module (scripts/api.js) + optional read-only snapshot bridge.obsidian-plugin/— plain JavaScript Obsidian plugin that imports/pushes campaign notes.tests/—npm test(node --test, no dependencies installed): Foundry sync toggle and pairing status, map pins and tokens, sidebar entries.
No DB seeding, no migrations, no linter/formatter, no Pinia/Vuex. Git: default branch master on a
self-hosted Gitea; .gitea/workflows/deploy.yml builds and deploys Docker images on push to master,
.gitea/workflows/test.yml runs npm test on every branch.
2. Commands
pnpm comes from corepack (packageManager in package.json); COREPACK_ENABLE_DOWNLOAD_PROMPT=0
keeps corepack from asking in non-interactive shells.
pnpm install # whole workspace, one lockfile (`-r` / `--filter <pkg>` for a single one)
pnpm dev # backend :5000 + frontend :3000 + discord-bot + scripts/run-foundry.js
pnpm dev:backend # or dev:frontend | dev:discord-bot
pnpm --filter ./frontend run build # or preview
pnpm test
No start script in backend/frontend and no lint command. Verification = run the dev server and
exercise the flow (GET /api/test returns a JSON hello).
There is no PM2 and no ecosystem.config.js: pnpm dev starts every dev process at the same time
through the workspace (concurrently only labels them and kills them together), and production runs
from the compose images (CMD of each Dockerfile).
Env: backend/.env (PORT is read but ignored, DB_URI), frontend/.env (NUXT_PUBLIC_API_BASE_URL),
both gitignored; the .env.production files are committed. backend/src/index.js loads .env.$NODE_ENV
when NODE_ENV is set, otherwise .env. The server always listens on 5000.
3. Backend
src/models/ one Mongoose schema per file · src/routes/ thin Express routers · src/services/
shared infra (keys.js JWT secret, passport.js JwtStrategy, storage.js multer → src/uploads/
served publicly at /api/public, rate-limiter.js 150 req/60 min, service-links.js the service
pairing in §4, *-foundry.js Foundry document → Dragonroll field mappers).
Auth chain, order matters (src/index.js): /api/public/* static → /api/user, /api/discord,
/api/link, /api/foundry (link + sync, token-authenticated) are mounted before
checkAuth = passport.authenticate('jwt', {session:false}); everything after it
(/api/campaign|note|folder|actor|item|map|foundry) is JWT-protected. checkAuth is assigned without
const (implicit global). New user routes are public unless the handler calls
passport.authenticate('jwt', {session:false}) inline (/upload-avatar, /update-settings,
/get-settings). JWT: payload {_id, username, name, email, admin, settings}, 48h; req.user is the
Mongoose document, so routes use req.user.id.
CORS allows any origin for the service link/sync paths only; the app-wide CORS whitelists
http://localhost:3000 and nothing else (production hides behind the nginx same-origin proxy).
Response envelope — always HTTP 200, no real status codes:
{ "status": "ok", ...payload }
{ "status": "error", "msg": "errors.internal" } // msg is an i18n KEY, not prose
Common keys: errors.missing-data, errors.notfound, errors.internal, unauthorized,
login.errors.invalid-credentials, register.errors.email-username-exists. GET /user/has-admin
returns status: 'init' when no admin exists yet (→ first-run registration).
Authorization — single-tenant: a campaign belongs to createdBy, everything else hangs off a
campaign, and handlers check ownership with a userOwnsCampaign(campaignId, userId) helper that is
duplicated per router file (match that unless you refactor all at once). settings, color,
description are free-form fields.
Models (* = required; notes and folders are always ordered date: -1):
User—name*,username*,email*(both unique),password(bcrypt, 10 rounds),admin,image,setupCode,settingsCampaign—name*,createdBy*→User,description,color,settings,foundryWorldId/foundryWorldTitle/foundrySystem,foundrySyncTokenHash(select: false),discordGuildIdNote—title,content(markdown source),campaign*,folder(null = root),colorFolder—name*,campaign*,parentFolder(null = root, self-ref),colorActor—name*,campaign*,foundryActorId(unique per campaign),discordUserId(the Discord player holding the character, unique per campaign — set only byroutes/discord.js), plus free-form sheet fields (type,species,className,level,abilityScores,armorClass,speed,proficiencies,traits,spells,image) andinventory[{name,quantity,weight}](flattened Foundry items, notItemdocs)Item—name*,campaign*,foundryItemId(unique per campaign),foundryNames,category,rarity,quantity,weight,properties,descriptionMap—name*,campaign*,image(filename insrc/uploads),gridSize/offsetX/offsetY/scale(image px),pins[{note→Note, x, y}](addressed by the pin's own_id),tokens[{actor→Actor, x, y}](the centre of the grid cell the token stands in, also addressed by its own_id)ServiceLinkRequest— the pending/completed service pairings of §4;DiscordGuildLinkmaps a Discord guild to the Dragonroll user who claimed it
API surface (all under /api, all {status,msg}):
user—register,verify-setup?code=,setup?code=,login({usermail,password}, accepts username or email →{token}),upload-avatar(multipartimage, JWT) /retrieve-avatar?username=,has-admin,update-settings/get-settings. Files fetched from/api/public/<filename>.campaign—create,update,list,retrieve/:id,services+service-unlink(what is linked to a campaign)note—list?campaign=(root notes + folders withparentFolder),subfolder/list?campaign=&folder=,all?campaign=(titles only, for the map pin picker),retrieve/:id,create,update(partial),deletefolder—list,create,update,rename,delete(recursive: inner notes go tofolder: null, subfolders re-parent then delete)actor—list,create,update(partial, ownership checked),upload-image?actor=(multipart),deleteitem—list,create,update(partial),deletemap—list,create(multipartimageor JSON),update(multipart to replace the photo),delete,pin({id,note,x,y}, re-pinning moves the marker),unpin({id,pin}),place-token({id,actor,x,y}, snapped to a cell centre, re-placing moves the token),remove-token({id,token})foundry— read-only proxy over the bridge (/world,/actors,/characters,/items,/actors/:id,/items/:id,/actors/:id/items), needsFOUNDRY_API_URL;POST /import({campaign, kind: 'actors'|'items'}, the sidebar's "force import from Foundry") pulls that world's whole list off the bridge through the sync's writers, so rows the campaign already has are written over, and answers{imported, updated};/icons?campaign=&dir=&offset=lists one folder of the world's coreicons/library (the bridge reads it fromDRAGONROLL_FOUNDRY_DATA_PATH) and answers{dir, parent, folders, files[{path,name,url}], next}, the icons paged so the library stays lazy to load
4. Service integrations (Foundry, Discord, Obsidian)
Every external service links to a campaign the same way, never with a Dragonroll login: it calls
POST /api/link/start, shows the returned sign-up link, and the user opens it in the frontend
(/link/authorize, handled by views/ServiceLinkAuthorize.vue outside the window app), signs in and
picks a campaign at POST /api/link/complete; the service then redeems its credential once at
POST /api/link/pickup (one-time; losing it means a new link). Proofs differ per service
(services/service-links.js): the Discord bot proves itself with the shared secret header, Foundry and
Obsidian only hold their link code, so what a link grants is decided by the user. Codes are hashed at
rest, expire after 10 min, and Obsidian gets a long-lived (365 d) token back.
Foundry then syncs with that token on /api/foundry/sync/* (routes/foundry-link.js, mounted before
the JWT guard; CORS opened for it): snapshot (actors + world items, fullSync also prunes),
item-snapshot, item-delete, characters, items, status, map / map-item, delete. Rules:
- Identity is
foundryActorId/foundryItemId(unique per campaign, partial index); a Foundry document carrying thedragonroll-foundry.actorId/.itemIdflag adopts the matching Dragonroll row. - Only the world's item directory reaches the item list (Syndria98/dragonroll#67) —
snapshotItemSourcesreadsbody.items(game.items) alone; gear embedded in a character is that actor'sinventory(see theActormodel), not anItem. A world item still folds into a hand-made or renamed row it matches by name (foundryNames), so a rename does not resurrect a duplicate.services/item-foundry.jsreturnsnullfor non-gear types and those are skipped. - Item folders mirror the world's item directory (
Folder.foundryFolderId, targetitem): every push carries the whole tree and the world owns its names and nesting.coloris the one field the campaign sets too, so it travels back with the foldersGET /foundry/sync/itemsanswers with ({items, folders}) and the module writes it onto the world's folder. fullSyncpreserves Dragonroll edits (only new rows are overwritten); live Foundry events overwrite. Only a full snapshot can prune.- Autosync is a Foundry-side setting (
autoSync, on by default): off = no CRUD push, no periodic reconcile, no startup snapshot; the actor directory's Dragonroll: Force Sync still upserts the selection (fullSync:false). GET /api/foundry/*(routes/foundry.js) is unrelated: a JWT-protected proxy over the read-only bridge. Its one write,POST /import, pulls the bridge's actors or world items into the campaign through the same writers as a sync push.
5. Frontend
5.1 Not a routed app
There is no app/pages/. app/app.vue renders a shell of managers (Window, Content, Toast,
Tooltip, ContextMenu) and boots: GetUser() (JWT in localStorage) → RestoreCampaign() or open
main_menu; no user → HasAdmin() ? 'login' : 'register' {firstTime:true}. The one real URL is
/link/authorize (and the legacy /discord/authorize), which renders the service link screen instead
of the app.
Two kinds of screens: windows (floating draggable/resizable overlays) and content — the
campaign workspace (TopBar + ContentSidebar + note column + StatusBar), turned on when
Campaign becomes non-null. The note column shows the open notes, or the anchored map
(ActivePane / AnchoredMap / AnchorMap in services/Content.js); viewer/map/MapViewerPane.vue
renders it both there and in the detached map_viewer window. Right-clicking that map pins a campaign
note at the spot (services/MapPins.js translates image px ↔ screen), clicking the marker opens
pinned_note. Dragging an actor row out of the sidebar onto the map makes it stand on that grid cell
as a token (services/MapTokens.js snaps to cell centres and sizes the token by its cell); the token
drags on with the pointer, steps over the grid with the arrow keys, and Delete takes it off.
5.2 The window system
services/WindowDefinitions.js is the registry ({ title: 'i18n.key', component: () => import(...), movable, close?, back? })
and services/Windows.js the runtime: CreateWindow(type, data) (one instance per type),
CreateChildWindow(parentId, ...), ClearWindow({type}|{id}), GetWindowWithId, GetFirstWindowId,
CallWindow(id, fn, arg), SetSize/SetPosition/ResetPosition(id,'center')/SetMinSize/SetMaxSize/Top,
getComponent(type), SetupHandle(id, handleRef). Adding a window = registry entry + component in
components/windows/; copy ExampleWindow.vue: props ['data'] (merged window object, props.data.id),
and in onMounted call Top(wrapper), SetupHandle(id, handle), SetSize, ResetPosition.
DOM ids these services depend on — do not rename: window-wrapper-{id}, window-handle-{id},
window-resize-handle-{id}, context-menu, mouse-tooltip.
5.3 Services are the state layer
app/services/ are plain ES modules with module-scope ref()s — no DI, no store, singleton by import.
Server.js (axios factory: Server().get(...), interceptor adds Authorization: Bearer <localStorage.token>,
initApi() from plugins/api.ts), User.js (GetUser/SetUser/LogoutUser/HasAdmin, GetUserSetting/
SetUserSetting server-backed in User.settings), Campaign.js (useCampaignService(), SetCampaign
writes localStorage.selectedCampaignId, RestoreCampaign), Content.js (§5.1), Emitter.js
(mitt() bus), Toaster.js, Tooltip.js, ContextMenu.js, Sound.js (AddSound binds
snap.wav to .sound-click), Marker.js (marked + widgets), ActionRegistry.js (command palette:
register/unregister/search/execute), Windows.js / WindowDefinitions.js, MapPins.js, MapTokens.js,
widgets/DiceParser.js.
5.4 Markdown → widgets
Marker.js turns @name\n…\n@end (block), @name[text] (inline) and [[target]] (wiki link) into
placeholder divs/spans; Note.vue renders with v-html and then mounts each placeholder with its own
createApp(GetWidget(kind, name), {content}) (and unmounts them on re-render). So widgets are isolated
mini-apps: they get only the content string and must not rely on the parent app's provides/injection.
Register one in widget_map in Marker.js, component in components/viewer/widgets/{inline,display}/.
DiceParser.js evaluates \d*d\d+ with adv|dis|kh<N>|kl<N>, + - * / ( ), unary minus, floor
division, and returns {total, steps[]} that RollWidgetDisplay.vue draws.
5.5 Event bus
Events in use: toast, push-note, close-note (removes from the open column only), delete-note
(closes and removes from the sidebar, and drops map pins — the note's close button must not use it),
title-updated, campaign-entry-created / campaign-entry-updated, note-created, note-renamed,
folder-saved, folder-deleted, status-bar-update. Payloads are API documents; the UI note shape is
{key, title, text, date}, mapped at the boundary as ContentSidebar.fetchCampaignNotes does. Always
import { emitter } from '~/services/Emitter' — composables/useEmitter.ts is broken (§8).
5.6 Styling, i18n
colors.scss Sass maps (dark/light, accents katlum/solus/silang) become --color-* CSS
variables: always style with var(--color-…), never hardcode hex, and add a new key to both maps.
useTheme.ts persists theme/accent and sets data-theme/data-accent on <html>; app.vue forces
setTheme('dark'). Icons are white SVGs with .icon (inverted via --color-icon-invert), from
/icons/... or the pixelarticons package. Fonts (fonts.scss, 5e-style families) and sounds
(/sounds/*.wav) live in public/.
i18n: frontend/i18n/locales/<lang>/<namespace>.json for en (default), es, ca; plugins/i18n.ts
nests each file under its filename, so the key is <file>.<path> ($t('windows.login')). Add every
new string to all three locales. Namespaces in use: general, login, register, main-menu,
settings, windows, campaigns, link, foundry, discord.
6. Conventions
- Backend: CommonJS; every handler
try/catch→{status:'error', msg:'errors.internal'}+console.error. - Frontend: Vue 3
<script setup>, PascalCase exported service functions (CreateWindow,GetUser), PascalCase component filenames, kebab-case DOM ids. Both~/and@/resolve toapp/— use what the neighbouring file uses. - Components call
Server()directly (no api layer);awaitand.thenboth appear. - Comments mix English and Catalan ("Moure aixo") — do not translate unrelated comments while editing.
- No formatter: keep diffs minimal and local, the codebase is deliberately rough.
7. Recipes
- New API resource:
models/X.js+routes/x.js(ownership check +{status,msg}envelope), thenapp.use('/api/x', require('./routes/x'))insrc/index.jsaftercheckAuthif it needs auth. - New window:
WindowDefinitions.jsentry +components/windows/X.vue(§5.2) + strings ini18n/locales/*/windows.json(all three locales). - New widget: component in
components/viewer/widgets/{inline,display}/+widget_mapentry inMarker.js. - New palette action:
register({id, label, description, execute, isActive?})from~/services/ActionRegistry(palette:Ctrl/Cmd+Kor/). - New theme color: key in both
darkandlightmaps incolors.scss, thenvar(--color-<key>).
8. Known landmines (verified in code — do not "fix" silently, never make them worse)
README.mdsays run./install.sh/./start.sh; neither exists.frontend/README.mdsays the frontend is React; it is Nuxt/Vue.services/keys.jsships the JWT secret"putyoursecrethere", used in production.POST /api/user/registerresponds{status:'ok', code: setupCode}butsetupCodeis not in scope → caught → the first-run registration actually returnserrors.internal. The register UI (RegisterWindow.vue) drives that flow; fix carefully.POST /api/note/deletehas no ownership check (any authenticated user can delete any note id); the othernote.jshandlers andfolder.jsdo check./api/user/*is mounted before the JWT guard: new routes there are public unless they authenticate inline (/api/discordis also before it, but every route there is gated byrequireBot, the shared bot-secret header).services/middleware.js'sisAdminis imported but applied to no route.composables/useEmitter.tsreads$emitterfromuseNuxtApp()and no plugin provides it — use~/services/Emitter.- App-wide CORS only whitelists
http://localhost:3000;.env.productionfiles are committed with internal hosts. Windows.js:getComponentcachesdefineAsyncComponentper type for the whole process (restart the dev server if a new window misbehaves),SetupHandleattachesdocumentmouse listeners per window and never removes them, andClearAll()iteratesObject.keys(windows)instead ofwindows.value.- The frontend treats the JWT as the user cache:
settingschanges needGetUserSetting/SetUserSettinground-trips, the token payload goes stale.
9. Ports
frontend dev :3000 · backend :5000 (hardcoded) · MongoDB :27017 · nginx :3000 → 80 in compose,
proxying / → frontend, /api/ → backend.