Fix issue #30: Make AGENTS.md smaller
All checks were successful
Test / test (push) Successful in 1s
All checks were successful
Test / test (push) Successful in 1s
This commit is contained in:
693
AGENTS.md
693
AGENTS.md
@@ -1,591 +1,224 @@
|
||||
# AGENTS.md — Dragonroll
|
||||
|
||||
Read this file before touching the code. It is a complete map of the project: layout, architecture,
|
||||
data model, API, conventions and known landmines. You should not need to explore the rest of the repo
|
||||
to make a correct change.
|
||||
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
|
||||
|
||||
**Dragonroll** is a free/open-source helper for tabletop RPG campaigns (notes, campaigns, folders,
|
||||
dice widgets, shared markdown, sounds). It is a two-app monorepo:
|
||||
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.
|
||||
- `frontend/` — **Nuxt 4 / Vue 3** client (Composition API, `<script setup>`), SCSS, axios, marked, mitt, motion.
|
||||
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth, CommonJS, entry `src/index.js`.
|
||||
- `frontend/` — **Nuxt 4 / Vue 3** (`<script setup>`), SCSS, axios, marked, mitt, motion, entry `app/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, sidebar entries.
|
||||
|
||||
There is **no** database seeding, no ORM migrations, no linter/formatter config, no Pinia/Vuex, and no
|
||||
Vue Router pages (see §5.1 — the UI is a window manager, not routed pages). The only automated tests
|
||||
are `tests/*.test.js` (`npm test`, Node's built-in runner), which exercise the Foundry module's sync
|
||||
logic against stubbed Foundry globals.
|
||||
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.
|
||||
|
||||
Git: default branch `master`, hosted on a self-hosted Gitea (`git.aranroig.com/BinarySandia04/Dragonroll`).
|
||||
CI (`.gitea/workflows/deploy.yml`) builds two Docker images on every push to `master`, pushes them to
|
||||
`git.aranroig.com/<user>/dragonroll-{frontend,backend}:latest`, copies `docker-compose.yml` +
|
||||
`nginx.conf` to the deploy host and runs `docker compose pull && up -d`.
|
||||
`.gitea/workflows/test.yml` runs the `npm test` suite (frontend + Foundry module tests, no dependencies
|
||||
installed) on every push to any branch, not just `master`.
|
||||
|
||||
## 2. Root layout
|
||||
|
||||
```
|
||||
dragonroll/
|
||||
├── backend/ Express API (CommonJS, entry: src/index.js)
|
||||
├── frontend/ Nuxt 4 app (entry: app/app.vue)
|
||||
├── obsidian-plugin/ Plain JavaScript Obsidian plugin for campaign note import/push
|
||||
├── docker-compose.yml nginx :3000 -> frontend :3000, /api -> backend :5000
|
||||
├── nginx.conf reverse proxy rules for the compose stack
|
||||
├── ecosystem.config.js PM2 config (stale: runs `npm start`, which does not exist — see §9)
|
||||
├── .gitea/workflows/deploy.yml
|
||||
├── static/media/ README logo images only
|
||||
├── tests/ `node --test` tests (Foundry module sync toggle)
|
||||
├── package.json root: only `concurrently`, used by `npm run dev`
|
||||
└── README.md install/run instructions are STALE (see §9)
|
||||
```
|
||||
|
||||
## 3. Commands
|
||||
## 2. Commands
|
||||
|
||||
```bash
|
||||
npm install # root: installs `concurrently` only
|
||||
npm install --prefix backend
|
||||
npm install --prefix frontend # runs `nuxt prepare` via postinstall
|
||||
|
||||
npm run dev # both apps: backend (nodemon, :5000) + frontend (nuxt dev, :3000)
|
||||
# also runs the Foundry VTT start script from root .env
|
||||
# (FOUNDRY_START_SCRIPT, via scripts/run-foundry.js)
|
||||
npm --prefix backend run dev # backend only
|
||||
npm --prefix frontend run dev # frontend only
|
||||
npm --prefix frontend run build # nuxt build --dotenv .env.production
|
||||
npm --prefix frontend run preview
|
||||
|
||||
npm test # node --test tests/ (Foundry module sync logic, no dependencies)
|
||||
npm install --prefix backend && npm install --prefix frontend # root `npm install` = concurrently only
|
||||
npm run dev # backend :5000 + frontend :3000 + discord-bot + scripts/run-foundry.js
|
||||
npm --prefix backend run dev # or --prefix frontend run dev | build | preview
|
||||
npm test
|
||||
```
|
||||
|
||||
There is no `start` script in either package and no lint command.
|
||||
Verification = run the dev server and exercise the flow (`/api/test` returns a JSON hello);
|
||||
`npm test` covers the Foundry character/item sync toggle and per-actor force sync.
|
||||
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).
|
||||
|
||||
### Environment files
|
||||
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**.
|
||||
|
||||
| File | Contents | Notes |
|
||||
|---|---|---|
|
||||
| `.env` (root) | `FOUNDRY_START_SCRIPT=<path to Foundry VTT start.sh>` | gitignored; consumed by `scripts/run-foundry.js` during `npm run dev` |
|
||||
| `backend/.env` | `PORT=5000`, `DB_URI=mongodb://localhost:27017/dragonroll`, `NODE_ENV=development` | gitignored |
|
||||
| `backend/.env.production` | same shape, `DB_URI=mongodb://192.168.1.7:27017/dragonroll` | **committed** |
|
||||
| `frontend/.env` | `NUXT_PUBLIC_API_BASE_URL=http://localhost:5000/api` | gitignored |
|
||||
| `frontend/.env.production` | `NUXT_PUBLIC_API_BASE_URL=https://dragonroll.aranroig.com/api` | **committed** |
|
||||
## 3. Backend
|
||||
|
||||
`backend/src/index.js` loads `.env.$NODE_ENV` when `NODE_ENV` is set, otherwise plain `.env`.
|
||||
`PORT` is read from env but **ignored**: the server always listens on 5000.
|
||||
`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).
|
||||
|
||||
## 4. Backend
|
||||
|
||||
```
|
||||
backend/src/
|
||||
├── index.js app bootstrap: dotenv, static uploads, json limits (50mb),
|
||||
│ passport init, CORS, route mounting, listen(5000)
|
||||
├── db.js connectDB() -> mongoose.connect(process.env.DB_URI)
|
||||
├── models/ User.js Campaign.js Note.js Folder.js Actor.js Item.js Map.js
|
||||
│ FoundryLinkRequest.js DiscordLinkRequest.js DiscordGuildLink.js
|
||||
├── routes/ user.js campaign.js note.js folder.js actor.js item.js map.js
|
||||
│ foundry-link.js (token sync, mounted BEFORE auth) foundry.js (bridge proxy)
|
||||
│ discord.js
|
||||
├── services/
|
||||
│ ├── keys.js { secret: "putyoursecrethere" } <- JWT secret, hardcoded
|
||||
│ ├── passport.js JwtStrategy: Bearer token -> User.findById(jwt_payload._id)
|
||||
│ ├── middleware.js isAdmin — imported by routes/user.js but applied to no route yet
|
||||
│ ├── rate-limiter.js express-rate-limit: 150 req / 60 min, applied to /user/login and /user/setup
|
||||
│ ├── storage.js multer diskStorage -> backend/src/uploads/, filename `<field>-<timestamp><ext>`
|
||||
│ ├── foundry.js requestFoundry(): reads the optional snapshot bridge
|
||||
│ ├── foundry-fields.js shared asText/numberOr/plainText/stringList for the mappers
|
||||
│ ├── actor-foundry.js foundryActorToCharacter(): Foundry actor document -> Actor fields
|
||||
│ └── item-foundry.js foundryItemToItemData(): Foundry item document -> Item fields
|
||||
└── uploads/ created on demand, gitignored, served PUBLICLY at /api/public
|
||||
```
|
||||
|
||||
### Auth chain (order matters, `src/index.js`)
|
||||
|
||||
1. `/api/public/*` → static file serving of `src/uploads` (no auth).
|
||||
2. `app.use('/api/user', routes/user)` → **mounted before the JWT guard**, so the whole user router is
|
||||
reachable unauthenticated. Individual handlers that need a user call
|
||||
**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`).
|
||||
3. `checkAuth = passport.authenticate('jwt', { session: false })` — note the **missing declaration**
|
||||
(implicit global). Everything mounted after this is JWT-protected.
|
||||
4. `/api/campaign`, `/api/note`, `/api/folder`, `/api/actor`, `/api/item` and `/api/foundry`
|
||||
(the read-only bridge proxy). `routes/foundry-link.js` is deliberately mounted **before** step 3 —
|
||||
it authenticates with the per-campaign sync token instead of a Dragonroll login (see §4.1).
|
||||
`/get-settings`). JWT: payload `{_id, username, name, email, admin, settings}`, 48h; `req.user` is the
|
||||
Mongoose document, so routes use `req.user.id`.
|
||||
|
||||
JWT: signed in `POST /api/user/login` with payload `{ _id, username, name, email, admin, settings }`,
|
||||
`expiresIn: 172800` (48h). `req.user` is the Mongoose `User` 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 convention
|
||||
|
||||
Every endpoint returns HTTP 200 with a JSON envelope; there is almost no real status-code usage:
|
||||
**Response envelope** — always HTTP 200, no real status codes:
|
||||
|
||||
```jsonc
|
||||
{ "status": "ok", ...payload }
|
||||
{ "status": "error", "msg": "errors.internal" } // msg is an i18n KEY, not prose
|
||||
```
|
||||
|
||||
Common `msg` keys: `errors.missing-data`, `errors.notfound`, `errors.internal`, `unauthorized`,
|
||||
`login.errors.invalid-credentials`, `register.errors.email-username-exists`. The frontend checks
|
||||
`response.data.status !== 'ok'`. `GET /user/has-admin` uses a special `status: "init"` to mean
|
||||
"no admin exists yet → show first-run registration".
|
||||
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 model
|
||||
**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.
|
||||
|
||||
Single-tenant per user: a campaign belongs to `createdBy`, everything else hangs off a campaign.
|
||||
`note.js` and `folder.js` define a local helper:
|
||||
**Models** (`*` = required; notes and folders are always ordered `date: -1`):
|
||||
|
||||
```js
|
||||
async function userOwnsCampaign(campaignId, userId) { ... } // duplicated in both files
|
||||
```
|
||||
- `User` — `name*`, `username*`, `email*` (both unique), `password` (bcrypt, 10 rounds), `admin`, `image`, `setupCode`, `settings`
|
||||
- `Campaign` — `name*`, `createdBy*`→User, `description`, `color`, `settings`, `foundryWorldId`/`foundryWorldTitle`/`foundrySystem`, `foundrySyncTokenHash` (`select: false`), `discordGuildId`
|
||||
- `Note` — `title`, `content` (markdown source), `campaign*`, `folder` (null = root), `color`
|
||||
- `Folder` — `name*`, `campaign*`, `parentFolder` (null = root, self-ref), `color`
|
||||
- `Actor` — `name*`, `campaign*`, `foundryActorId` (unique per campaign), plus free-form sheet fields (`type`, `species`, `className`, `level`, `abilityScores`, `armorClass`, `speed`, `proficiencies`, `traits`, `spells`, `image`) and `inventory[{name,quantity,weight}]` (flattened Foundry items, **not** `Item` docs)
|
||||
- `Item` — `name*`, `campaign*`, `foundryItemId` (unique per campaign), `foundryNames`, `category`, `rarity`, `quantity`, `weight`, `properties`, `description`
|
||||
- `Map` — `name*`, `campaign*`, `image` (filename in `src/uploads`), `gridSize`/`offsetX`/`offsetY`/`scale` (image px), `pins[{note→Note, x, y}]` (addressed by the pin's own `_id`)
|
||||
- `ServiceLinkRequest` — the pending/completed service pairings of §4; `DiscordGuildLink` maps a Discord guild to the Dragonroll user who claimed it
|
||||
|
||||
Ownership is enforced per handler. `settings`, `color`, `description` and `User.settings` are schemaless
|
||||
`Object`/free-form fields.
|
||||
**API surface** (all under `/api`, all `{status,msg}`):
|
||||
|
||||
### Data model
|
||||
- `user` — `register`, `verify-setup?code=`, `setup?code=`, `login` (`{usermail,password}`, accepts username or email → `{token}`), `upload-avatar` (multipart `image`, 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 with `parentFolder`), `subfolder/list?campaign=&folder=`, `all?campaign=` (titles only, for the map pin picker), `retrieve/:id`, `create`, `update` (partial), `delete`
|
||||
- `folder` — `list`, `create`, `update`, `rename`, `delete` (recursive: inner notes go to `folder: null`, subfolders re-parent then delete)
|
||||
- `actor` — `list`, `create`, `update` (partial, ownership checked), `upload-image?actor=` (multipart), `delete`
|
||||
- `item` — `list`, `create`, `update` (partial), `delete`
|
||||
- `map` — `list`, `create` (multipart `image` or JSON), `update` (multipart to replace the photo), `delete`, `pin` (`{id,note,x,y}`, re-pinning moves the marker), `unpin` (`{id,pin}`)
|
||||
- `foundry` — read-only proxy over the bridge (`/world`, `/actors`, `/characters`, `/items`, `/actors/:id`, `/items/:id`, `/actors/:id/items`), needs `FOUNDRY_API_URL`
|
||||
|
||||
```
|
||||
User ──< Campaign ──< Note ──?> Folder ──?> Folder (parentFolder, self-ref)
|
||||
└───────< Folder
|
||||
└───────< Actor (Foundry actors, when linked)
|
||||
└───────< Item (Foundry gear + hand-made items)
|
||||
└───────< Map (uploaded images + their grid settings)
|
||||
```
|
||||
## 4. Service integrations (Foundry, Discord, Obsidian)
|
||||
|
||||
| Model | File | Fields |
|
||||
|---|---|---|
|
||||
| `User` | `models/User.js` | `name*`, `username*` (unique), `email*` (unique), `password` (bcrypt hash, 10 salt rounds), `date`, `admin` (bool, default false), `image`, `setupCode`, `settings` (Object) |
|
||||
| `Campaign` | `models/Campaign.js` | `name*`, `description`, `color`, `createdBy*` → User, `date`, `settings` (Object), `foundryWorldId` (unique, sparse), `foundryWorldTitle`, `foundrySystem`, `foundrySyncTokenHash` (`select: false`), `discordGuildId` |
|
||||
| `Note` | `models/Note.js` | `title`, `content` (markdown source string), `campaign*` → Campaign, `folder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
||||
| `Folder` | `models/Folder.js` | `name*`, `campaign*` → Campaign, `parentFolder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
||||
| `Actor` | `models/Actor.js` | `name*`, `type` (`character`\|`npc`\|`creature`), `species`, `className`, `subclass`, `level`, `background`, `challengeRating`, `description`, `image`, `abilityScores{str..cha}`, `armorClass`, `speed`, `proficiencies`, `inventory[{name,quantity,weight}]` (flattened Foundry items, embedded — not `Item` docs), `traits`, `spells` (newline text), `campaign*` → Campaign, `foundryActorId` (unique per campaign), `date` |
|
||||
| `Item` | `models/Item.js` | `name*`, `category` (`weapon`\|`armor`\|`shield`\|`adventuring-gear`\|`magic-item`\|`consumable`\|`tool`\|`treasure`\|`other`), `rarity` (`common`…`artifact`), `quantity`, `weight`, `properties`, `description`, `campaign*` → Campaign, `foundryItemId` (unique per campaign), `foundryNames` (names Foundry uses for it, keeps dedup stable across a Dragonroll rename), `date` |
|
||||
| `Map` | `models/Map.js` | `name*`, `image` (filename in `src/uploads`), `gridSize` (cell size in image px), `offsetX`/`offsetY` (grid origin in image px), `scale` (distance one cell stands for), `pins[{note → Note, x, y}]` (a note pinned at image px coordinates, addressed by its own `_id`), `campaign*` → Campaign, `date` |
|
||||
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.
|
||||
|
||||
`*` = required. Notes and folders are ordered by `date: -1` everywhere.
|
||||
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:
|
||||
|
||||
### API reference
|
||||
|
||||
`POST /api/user/register` — body `{username,email,name,password}`. First registered user becomes
|
||||
`admin: true`. (Currently broken: see §9.)
|
||||
|
||||
`GET /api/user/verify-setup?code=` — `{status:'ok',code}` | `{status:'error',msg:'not-exists'}`
|
||||
|
||||
`POST /api/user/setup?code=` — rate limited. Body `{name,username,email,password}` completes an
|
||||
invited account (`setupCode` is cleared).
|
||||
|
||||
`POST /api/user/login` — rate limited. Body `{usermail,password}` (accepts username **or** email) →
|
||||
`{status:'ok', token, msg:'success'}`.
|
||||
|
||||
`POST /api/user/upload-avatar` — multipart field `image`, JWT required → stores filename on `User.image`.
|
||||
Fetch the file from `/api/public/<filename>`.
|
||||
|
||||
`GET /api/user/retrieve-avatar?username=` → `{status:'ok', image}`
|
||||
|
||||
`GET /api/user/has-admin` → `status: 'ok' | 'init' | 'error'`
|
||||
|
||||
`POST /api/user/update-settings` — JWT inline. Body `{ settings: {...} }` (whole object replaced).
|
||||
`GET /api/user/get-settings` — JWT inline → `{status:'ok', settings}`
|
||||
|
||||
`POST /api/campaign/create` — `{name,description,color,settings}` → `{status:'ok',campaign}`
|
||||
`GET /api/campaign/list` → `{status:'ok',campaigns}`
|
||||
`GET /api/campaign/retrieve/:id` → `{status:'ok',campaign}` (401 when no `req.user.id`)
|
||||
|
||||
`GET /api/note/list?campaign=` → `{status:'ok', folders, notes}` — notes with `folder: null` (roots);
|
||||
folder entries include `parentFolder` so clients can rebuild nested folder paths
|
||||
`GET /api/note/subfolder/list?campaign=&folder=` → `{status:'ok', subfolders, notes}`
|
||||
`GET /api/note/all?campaign=` → `{status:'ok', notes, folders}` — every note of the campaign, titles
|
||||
only (no `content`); the map viewer's note picker and its pin labels
|
||||
`GET /api/note/retrieve/:id` → `{status:'ok',note}` — one note with its content, ownership checked
|
||||
`POST /api/note/create` — `{title*,content,campaign*,folder?}` (folder validated against campaign)
|
||||
`POST /api/note/update` — `{id*, title?, content?, folder?, color?}` — partial, ownership checked
|
||||
`POST /api/note/delete` — `{id}` — **no ownership check** (§9); pulls the note off every map's `pins`
|
||||
|
||||
`GET /api/folder/list?campaign=` → `{status:'ok',folders}`
|
||||
`POST /api/folder/create` — `{name*,campaign*}`
|
||||
`POST /api/folder/rename` — `{id*,name*}`
|
||||
`POST /api/folder/update` — `{id*, name?, color?}` — partial, ownership checked
|
||||
`POST /api/folder/delete` — `{id}` — recursive: notes inside are moved to root (`folder: null`),
|
||||
subfolders re-parented to null then deleted.
|
||||
|
||||
`GET /api/test` — health check.
|
||||
|
||||
`GET /api/actor/list?campaign=` → `{status:'ok',actors}`
|
||||
`POST /api/actor/create` — `{name*,campaign*,type?,species?,className?,subclass?,level?,background?,challengeRating?,description?}`
|
||||
`POST /api/actor/update` — `{id*, name?, species?, className?, subclass?, level?, abilityScores?, armorClass?, speed?, proficiencies?, inventory?, traits?, spells?, image?}` — partial, ownership checked
|
||||
`POST /api/actor/upload-image?actor=` — multipart field `image`
|
||||
`POST /api/actor/delete` — `{id}`
|
||||
|
||||
`GET /api/item/list?campaign=` → `{status:'ok',items}`
|
||||
`POST /api/item/create` — `{name*,campaign*,category?,rarity?,quantity?,weight?,properties?,description?}`
|
||||
`POST /api/item/update` — `{id*, name?, category?, rarity?, quantity?, weight?, properties?, description?}` — partial, ownership checked. `''` for `quantity`/`weight` is ignored, like `/item/create`.
|
||||
`POST /api/item/delete` — `{id}`
|
||||
|
||||
`GET /api/map/list?campaign=` → `{status:'ok',maps}`
|
||||
`POST /api/map/create` — multipart (`image`) or JSON `{name*,campaign*,gridSize?,offsetX?,offsetY?,scale?}` → `{status:'ok',map}`
|
||||
`POST /api/map/update` — `{id*, name?, gridSize?, offsetX?, offsetY?, scale?}`, partial, ownership checked. Send it as
|
||||
multipart with an `image` field to replace the photo (multer reads the other fields from the form; JSON works too).
|
||||
`POST /api/map/delete` — `{id}`
|
||||
`POST /api/map/pin` — `{id*, note*, x, y}` — pins a note of the same campaign at those image px;
|
||||
pinning a note that is pinned already moves that marker → `{status:'ok',map}`
|
||||
`POST /api/map/unpin` — `{id*, pin*}` (`pin` is the subdocument `_id`) → `{status:'ok',map}`
|
||||
|
||||
### 4.1 Foundry integration (actors, items)
|
||||
|
||||
`dragonroll-foundry/` holds the Foundry VTT module (`scripts/api.js`, loaded by `module.json`) and an
|
||||
optional read-only snapshot bridge (`bridge/server.js`). The module talks to Dragonroll with a
|
||||
per-campaign bearer token, **not** a Dragonroll login: `POST /api/foundry/link/complete` redeems a
|
||||
pairing code, stores its hash on `Campaign.foundrySyncTokenHash` and hands the plain token to Foundry
|
||||
once. Every sync route re-reads the campaign from that hash and rejects payloads whose `worldId` is
|
||||
not `Campaign.foundryWorldId` (`syncCampaign` / `requestMatchesWorld`). CORS is opened for
|
||||
`/api/foundry/sync*` and `/foundry/link/complete` in `src/index.js`, before the app-wide CORS.
|
||||
`dragonroll-foundry/README.md` documents pairing, the bridge and its environment variables.
|
||||
|
||||
| Sync route (token) | Meaning |
|
||||
|---|---|
|
||||
| `POST /sync/snapshot` | `{worldId, actors[], items[], fullSync}` — upserts actors, world items and every item embedded in those actors; a `fullSync` also deletes actors/items that are gone |
|
||||
| `POST /sync/item-snapshot` | `{worldId, items[]}` — live world-item edits, upsert only (never prunes) |
|
||||
| `POST /sync/item-delete` | `{worldId, foundryItemId}` — a world item was deleted |
|
||||
| `GET /sync/characters` | Actors the module applies back into Foundry |
|
||||
| `GET /sync/items` | Items the module applies back into Foundry (creates world items for Dragonroll-authored ones) |
|
||||
| `GET /sync/status` | The campaign a sync token belongs to; the module shows it in its **Dragonroll Pairing Status** setting and treats `unauthorized` as the campaign having unlinked the world |
|
||||
| `POST /sync/map` / `POST /sync/map-item` | Store the id mapping after the module creates a document |
|
||||
| `POST /sync/delete` | `{worldId, foundryActorId}` |
|
||||
|
||||
Rules worth knowing before editing this:
|
||||
|
||||
- **Identity** is `foundryActorId` / `foundryItemId` (unique per campaign, partial index so local
|
||||
documents can leave it unset). A document carrying the `dragonroll-foundry.actorId` /
|
||||
`dragonroll-foundry.itemId` flag adopts the matching Dragonroll row.
|
||||
- **Items are deduplicated by name.** Foundry keeps the same gear once per carrier, so one Dragonroll
|
||||
`Item` per name: the first document to claim it keeps the mapping, later copies just return it.
|
||||
`foundryNames` remembers Foundry's names so a Dragonroll rename does not resurrect a duplicate.
|
||||
`services/item-foundry.js` returns `null` for non-gear types (spells, classes, feats, species…),
|
||||
which the sync skips.
|
||||
- **`fullSync` preserves Dragonroll edits** (only new rows are overwritten); live Foundry events
|
||||
overwrite. Item pruning requires the full snapshot, since only it sees world items and actor copies.
|
||||
- **Autosync is a Foundry-side switch** (`autoSync` client setting, on by default): when off, the
|
||||
module queues no CRUD push, runs no periodic reconcile and sends no startup snapshot; the actor
|
||||
directory's `Dragonroll: Force Sync` entry still pushes the selected actors as an upsert
|
||||
(`fullSync:false`, so it never prunes). The read-only bridge snapshot is not gated by it.
|
||||
- **`pairingStatus` is a setting the module writes, not the GM**: the module settings sentence about
|
||||
whether this world is connected comes from the stored sync token plus the answer from
|
||||
`/sync/status` (checked at world start and every minute), and anything typed into it is replaced.
|
||||
- `Actor.inventory` stays a flattened copy of the actor's embedded items; it is not linked to `Item`.
|
||||
- `GET /api/foundry/*` (`routes/foundry.js`) is unrelated: a JWT-protected proxy over the read-only
|
||||
bridge, only useful when `FOUNDRY_API_URL` is configured.
|
||||
- **Identity** is `foundryActorId` / `foundryItemId` (unique per campaign, partial index); a Foundry document carrying the `dragonroll-foundry.actorId` / `.itemId` flag adopts the matching Dragonroll row.
|
||||
- **Items are deduplicated by name** — Foundry keeps the same gear once per carrier, so one `Item` per name; `foundryNames` keeps Foundry's names so a Dragonroll rename does not resurrect a duplicate. `services/item-foundry.js` returns `null` for non-gear types and those are skipped.
|
||||
- **`fullSync` preserves 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.
|
||||
|
||||
## 5. Frontend
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── nuxt.config.ts css order (colors, fonts, main, callouts), runtimeConfig.public
|
||||
│ {apiBaseUrl, gitCommit, gitTag, gitBranch, buildDate}, @nuxtjs/i18n module,
|
||||
│ vite.optimizeDeps; git info harvested at build time via execSync
|
||||
├── 18n.config.ts vue-i18n fallbackLocale 'en'
|
||||
├── i18n/locales/ en/ es/ ca/ (+ empty en.json, es.json, ca.json for the nuxt module)
|
||||
├── public/ img/ icons/{iconoir/{regular,solid},Pixelarticons,ui} sounds/ fonts/{5e,amiri,...}
|
||||
│ → served at /img, /icons, /sounds, /fonts
|
||||
└── app/ Nuxt 4 source root (`~/` and `@/` both alias here)
|
||||
├── app.vue real entry: theme setup + start() boot logic + 5 managers
|
||||
├── assets/css/ colors.scss (theme maps → CSS vars), fonts.scss (5e-style font families),
|
||||
│ main.scss (globals, scrollbars, .icon), callouts.scss (Obsidian-like callouts)
|
||||
├── components/
|
||||
│ ├── managers/ WindowManager, ContentManager, ToastManager, TooltipManager, ContextMenuManager
|
||||
│ ├── windows/ ExampleWindow (template to copy), Login, Register, MainMenu, Settings,
|
||||
│ │ CreateCampaign, RenameNote, NewFolder + partials/{WindowHandle,
|
||||
│ │ FixedBottomButtons, BigIconTemplate}
|
||||
│ ├── partials/ ContentSidebar, NestedNoteList, CampaignEntry, EditUserPartial, Spinner,
|
||||
│ │ VersionRender
|
||||
│ ├── layouts/ IconButton, Dropdown, Tabs, ColorPicker (reusable UI atoms)
|
||||
│ └── viewer/ TopBar, statusbar/{StatusBar,FetchStatus}, topbar/{TopSearchBar,SearchResult},
|
||||
│ content/{Content,NoteContainer,Note}, map/MapViewerPane, widgets/{TableWidget,TestWidget,
|
||||
│ inline/RollWidgetInline,display/RollWidgetDisplay}
|
||||
├── composables/ useTheme.ts (theme+accent singletons, localStorage, data-* attrs),
|
||||
│ useEmitter.ts (BROKEN, see §9)
|
||||
├── plugins/ api.ts (inject runtimeConfig apiBaseUrl into the axios instance), i18n.ts
|
||||
└── services/ plain ES modules holding reactive module state (the app has no store)
|
||||
```
|
||||
### 5.1 Not a routed app
|
||||
|
||||
### 5.1 It is 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.
|
||||
|
||||
There is no `app/pages/`. `app/app.vue` renders a fixed shell of managers. "Screens" are either:
|
||||
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`.
|
||||
|
||||
- **Windows** — floating, draggable/resizable overlays (login, main menu, settings…), or
|
||||
- **Content** — the campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`),
|
||||
shown when `Campaign` state is non-null. The note column shows the open notes, or the map anchored
|
||||
on it (`AnchorMap` / `ActivePane` in `services/Content.js`); the sidebar's notes and maps buttons
|
||||
switch between the two while both keep their state, and `viewer/map/MapViewerPane.vue` renders the
|
||||
map there and inside the `map_viewer` window (a detached anchored map). Right clicking that map pins
|
||||
one of the campaign notes at the spot (`services/MapPins.js` translates between image pixels and
|
||||
the screen and labels the note picker); clicking the marker opens `pinned_note`
|
||||
(`PinnedNoteWindow.vue`), which reads the note itself through `/note/retrieve/:id`.
|
||||
### 5.2 The window system
|
||||
|
||||
Boot sequence (`app.vue` → `start()`):
|
||||
`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`.
|
||||
|
||||
```
|
||||
GetUser() (JWT in localStorage, un-expired)?
|
||||
├─ yes → RestoreCampaign() (localStorage.selectedCampaignId) → on failure open 'main_menu'
|
||||
└─ no → HasAdmin() ? open 'login' : open 'register' {firstTime:true}
|
||||
```
|
||||
DOM ids these services depend on — **do not rename**: `window-wrapper-{id}`, `window-handle-{id}`,
|
||||
`window-resize-handle-{id}`, `context-menu`, `mouse-tooltip`.
|
||||
|
||||
### 5.2 The window system (most important thing to understand)
|
||||
### 5.3 Services are the state layer
|
||||
|
||||
`app/services/WindowDefinitions.js` is the **registry**: key = window type, value =
|
||||
`{ title: 'i18n.key', component: () => import('~/components/windows/X.vue'), movable, close?, back?, ... }`.
|
||||
Adding a window = add an entry here **and** a component in `app/components/windows/`.
|
||||
`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`,
|
||||
`widgets/DiceParser.js`.
|
||||
|
||||
`app/services/Windows.js` is the runtime. Module-level state: `windows = ref([])`, auto-incrementing
|
||||
`currentId`, `currentIndex` z-index counter. Key exports:
|
||||
### 5.4 Markdown → widgets
|
||||
|
||||
`CreateWindow(type, data)` (one instance per type — duplicates are ignored),
|
||||
`CreateChildWindow(parentId, type, data)` (child dies with parent), `ClearWindow({type}|{id})`
|
||||
(recursive over `children`), `ClearAll()`, `GetWindowWithId(id)`, `GetFirstWindowId(type)`,
|
||||
`CallWindow(id, callableName, arg)`, `SetSize/SetPosition/SetMinSize/SetMaxSize/SetResizable/
|
||||
SetMovable/ResetPosition(id,'center')/SetOnTop/Top`, `getComponent(type)` (cached `defineAsyncComponent`),
|
||||
and `SetupHandle(id, handleRef)` which wires raw DOM mouse listeners for drag/resize.
|
||||
`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.
|
||||
|
||||
Contract a window component must fulfil (copy `ExampleWindow.vue`):
|
||||
### 5.5 Event bus
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { SetupHandle, SetSize, ResetPosition, Top } from '@/services/Windows';
|
||||
import WindowHandle from './partials/WindowHandle.vue';
|
||||
const handle = ref(null), wrapper = ref(null);
|
||||
const props = defineProps(['data']); // 'data' = merged {type,id,...WindowDefinitions entry,...CreateWindow data}
|
||||
const id = props.data.id;
|
||||
onMounted(() => {
|
||||
Top(wrapper); SetupHandle(id, handle);
|
||||
SetSize(id, { width: 500, height: 380 }); ResetPosition(id, 'center');
|
||||
});
|
||||
</script>
|
||||
<template>
|
||||
<div class="window-wrapper" :id="'window-wrapper-' + id" ref="wrapper">
|
||||
<WindowHandle :window="id" ref="handle"></WindowHandle>
|
||||
<!-- body -->
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
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).
|
||||
|
||||
DOM id conventions that `Windows.js`, `WindowHandle.vue` and drag/resize depend on — do not rename:
|
||||
`window-wrapper-{id}`, `window-handle-{id}`, `window-resize-handle-{id}`, `context-menu`, `mouse-tooltip`.
|
||||
### 5.6 Styling, i18n
|
||||
|
||||
`WindowHandle.vue` reads `title` (translated at mount via `$t`), `close` and `back` off the window
|
||||
object, exposes `setupHandle()`, and plays `/sounds/close.wav` when closed.
|
||||
`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/`.
|
||||
|
||||
### 5.3 Services (`app/services/`) — the state layer
|
||||
|
||||
Plain modules with module-scope `ref()`s imported directly. No DI, no Pinia. Singleton by import.
|
||||
|
||||
| Service | Provides |
|
||||
|---|---|
|
||||
| `Server.js` | axios instance (fallback baseURL `http://localhost:5000/api`), `initApi(baseURL)` called by `plugins/api.ts`, request interceptor adding `Authorization: Bearer <localStorage.token>`, `getBaseUrl()`. Default export is a factory: call `Server()` then `.get/.post`. |
|
||||
| `User.js` | `UserStatus` ref, `GetUser()` (decodes JWT, auto-logout on `exp`), `SetUser(token)`, `LoadUser`, `LogoutUser`, `IsAdmin`, `HasAdmin()`, `GetUserSetting(key)` / `SetUserSetting(key,value)` (server-backed, in `User.settings`) |
|
||||
| `Campaign.js` | `useCampaignService()` → `Campaign` (`useState('campaign')`), `SetCampaign(data)` (also writes `localStorage.selectedCampaignId`), `RestoreCampaign()` |
|
||||
| `Content.js` | `ShowContent` ref (drives the campaign workspace: `ContentManager.vue` turns it on from a `watch(Campaign)`, `TopBar` off when leaving a campaign) and the anchored map: `ActivePane` (`'notes'`\|`'map'`), `AnchoredMap`, `SetActivePane`, `AnchorMap`, `ClearAnchoredMap` |
|
||||
| `Emitter.js` | `export const emitter = mitt()` — the app-wide event bus |
|
||||
| `Toaster.js` | `DisplayToast(color, text, duration)` → emits `toast`; `ToastManager.vue` renders it |
|
||||
| `Tooltip.js` | `SetupTooltip()`, `AddTooltip(el, text, {max_width})` (stores on `el._dr_tooltip`), polled visibility via `elementsFromPoint` |
|
||||
| `ContextMenu.js` | `SetupContextMenu()`, `AddContextMenu(el, items, {dropdown:true})`, `ShowContextMenu(items)`, `HideContextMenu()`. Items: `{name, icon?, action?, divider?}` or `{name, context:[...]}` for a submenu; built imperatively into `#context-menu` with `motion` animations |
|
||||
| `Sound.js` | `AddSound(rootEl)` binds `/sounds/snap.wav` to every `.sound-click` inside `rootEl` |
|
||||
| `Marker.js` | marked `Marked` instance + custom extensions, `ParseMarkdown(src)`, `GetWidget(kind,name)` (§5.4) |
|
||||
| `ActionRegistry.js` | `register({id,label,description,execute,isActive?})`, `unregister`, `search(q)` (diacritic-insensitive, prefix-first sort), `execute(id,params)` — powers the command palette |
|
||||
| `Windows.js` / `WindowDefinitions.js` | §5.2 |
|
||||
| `widgets/DiceParser.js` | recursive-descent dice evaluator (§5.5) |
|
||||
|
||||
### 5.4 Markdown → Vue widgets
|
||||
|
||||
`Marker.js` registers three marked extensions:
|
||||
|
||||
| Syntax | Level | Output |
|
||||
|---|---|---|
|
||||
| `@name\n<content>\n@end` | block | `<div class="vue-component-display" data-component data-content>` |
|
||||
| `@name[text]` | inline | `<span class="vue-component-inline" data-component data-content>` |
|
||||
| `[[target]]` | inline | `<span class="vue-link" data-href>` (renders the literal text `Link`) |
|
||||
|
||||
`Note.vue` renders the HTML with `v-html`, then in a `setTimeout(...,0)` calls `mountComponents()`,
|
||||
which `querySelectorAll('.vue-component-display'|'.vue-component-inline')` and mounts each node with a
|
||||
**separate** `createApp(GetWidget(kind, el.dataset.component), { content: el.dataset.content })`.
|
||||
Widgets are therefore isolated mini-apps: they receive only `content` (a string) and must not rely on
|
||||
the parent app's provides/injection.
|
||||
|
||||
Registering a widget = add an entry to `widget_map` in `Marker.js`:
|
||||
|
||||
```js
|
||||
const widget_map = {
|
||||
inline: { roll: () => import("~/components/viewer/widgets/inline/RollWidgetInline.vue") },
|
||||
display: { roll: () => import("~/components/viewer/widgets/display/RollWidgetDisplay.vue") },
|
||||
};
|
||||
```
|
||||
|
||||
`Note.vue` also: handles `Ctrl/Cmd+E` (toggle edit/preview, saves on exit) and `Ctrl/Cmd+S` (save via
|
||||
`POST /note/update`), tracks dirty state (white dot in the vertical title strip), and wires
|
||||
Obsidian-style collapsible callouts (`setupCallout()`/`toggleCallout()` + `callouts.scss`).
|
||||
|
||||
### 5.5 Dice grammar (`DiceParser.js`)
|
||||
|
||||
`parse(expr) -> { total, steps[] }`. Tokens: `\d*d\d+` with optional `adv|dis|kh<N>|kl<N>`, integers,
|
||||
`+ - * / ( )`, unary minus. `adv`/`dis` roll 2dN and keep max/min; `kh`/`kl` keep highest/lowest N.
|
||||
Division is `Math.floor`. Guards: count 1–1000, sides 2–10000. `steps` are `{type:'op'|'const'|'dice'}`
|
||||
and `RollWidgetDisplay.vue` turns them into the visual breakdown (kept/dropped/max/min classes).
|
||||
|
||||
### 5.6 Event bus contract
|
||||
|
||||
Every listener in the app (there are only these six `emitter.on` call sites):
|
||||
|
||||
| Event | Payload | Listened by |
|
||||
|---|---|---|
|
||||
| `toast` | `{color,text,duration}` | `ToastManager.vue` |
|
||||
| `push-note` | `{key,title,text,date}` | `NoteContainer.vue` |
|
||||
| `close-note` | note key (string) | `NoteContainer.vue` (removes the note from the open column only) |
|
||||
| `delete-note` | note key (string) | `NoteContainer.vue`, `ContentSidebar.vue`, `NestedNoteList.vue` (real deletion: closes the note **and** removes it from the sidebar), `MapViewerPane.vue` (drops the markers pinned to that note) |
|
||||
| `title-updated` | `{key,title}` | `Note.vue`, `NoteContainer.vue`, `MapViewerPane.vue` (relabels the map pins of that note) |
|
||||
| `status-bar-update` | `{text,icon}` | `FetchStatus.vue` |
|
||||
|
||||
Emitters: `Toaster.js` (`toast`), `ContentSidebar` / `TopSearchBar` (`push-note`), `Note.vue`
|
||||
(`close-note` — the close button must not use `delete-note` or the sidebar entry disappears),
|
||||
`NestedNoteList.vue` (`delete-note`, after `POST /note/delete`), `ContentSidebar` (`title-updated`),
|
||||
`FetchStatus` (self-test emit).
|
||||
|
||||
**Orphan events** — emitted, never subscribed to anywhere (the matching handlers `handleNoteCreated` /
|
||||
`handleNoteRenamed` exist in `ContentSidebar.vue` but were never wired with `emitter.on`; see §9.17):
|
||||
|
||||
| Event | Emitted by | Intended handler |
|
||||
|---|---|---|
|
||||
| `note-created` | `ContentSidebar.createNote`, `TopSearchBar` | `ContentSidebar.handleNoteCreated` (dead) |
|
||||
| `note-renamed` | `RenameNoteWindow.vue` | `ContentSidebar.handleNoteRenamed` (dead) |
|
||||
| `folder-saved` | `NewFolderWindow.vue` | none — sidebar refreshes only via `@reload-notes` from `NestedNoteList` |
|
||||
|
||||
So "create note" currently works because the sidebar mutates its own list, and folder changes need an
|
||||
explicit `fetchCampaignNotes()`. If you rely on an event, check a listener exists.
|
||||
|
||||
Note object shape in the UI layer is `{ key, title, text, date }` (mapped from the API's
|
||||
`{_id,title,content,date}`); convert at the boundary as `ContentSidebar.fetchCampaignNotes` does.
|
||||
|
||||
### 5.7 Theming, fonts, icons, sounds
|
||||
|
||||
- `useTheme.ts` owns `theme` (`'light'|'dark'`) and `accent` (`'katlum'`, type currently narrow) as
|
||||
module singletons, persists to `localStorage`, and sets `data-theme` / `data-accent` on `<html>`.
|
||||
`app.vue` calls `setupTheme()` then forces `setTheme('dark')` on mount.
|
||||
- `colors.scss` holds Sass maps `dark`/`light` (and accents `katlum`/`solus`/`silang`) emitted as
|
||||
**`--color-*` CSS variables**. Always style with `var(--color-...)` (`background`,
|
||||
`window-background`, `button-hover`, `text`, `border`, `icon-invert`, …), never hardcode hex.
|
||||
- Icons are inverted via `filter: invert(var(--color-icon-invert))` — white SVGs + `.icon` class.
|
||||
Reference either as public assets (`/icons/iconoir/regular/xmark.svg`, `/icons/ui/...`,
|
||||
`/icons/Pixelarticons/white/close.svg`) or from the `pixelarticons` npm package
|
||||
(`import SearchIcon from 'pixelarticons/svg/search.svg'`).
|
||||
- Fonts (`fonts.scss` + `public/fonts/5e`): `BookInsanityRemake` (body default), `MrEavesRemake`
|
||||
(headings/window titles), `ScalySansRemake`, `NodestoCapsCondensed`, `SolberaImitationRemake`, etc.
|
||||
- Sounds in `public/sounds/`: `snap.wav` (the `.sound-click` default), `close.wav`, `click.wav`,
|
||||
`dice.wav`, `roll1.wav`, `roll2.wav`, `notify.wav`, `drums.wav`, `lock.wav`, `doors/`.
|
||||
|
||||
### 5.8 i18n
|
||||
|
||||
Locales: `en` (default), `es`, `ca`. Files live at `frontend/i18n/locales/<lang>/<namespace>.json`, and
|
||||
`app/plugins/i18n.ts` globs them and nests each under its **filename** — so the key is
|
||||
`<file>.<path>`, e.g. `i18n/locales/en/main-menu.json` → `$t('main-menu.create-campaign')`.
|
||||
Namespaces in use: `general`, `login`, `register`, `main-menu`, `settings`, `windows`, `campaigns`
|
||||
(`campaigns` currently only exists for `en`). Call it as `$t(...)` in templates or via `useI18n()` in
|
||||
script; `WindowDefinitions` stores raw keys (`title: 'windows.login'`) and `WindowHandle` translates them.
|
||||
|
||||
**Adding a string = add it to all three locales** (`en`, `es`, `ca`); the Nuxt i18n module is also
|
||||
configured (`nuxt.config.ts`, `langDir: 'locales/'`, `vueI18n: './i18n.config.ts'`) but its locale files
|
||||
(`locales/en.json` etc.) are empty `{}` — the custom plugin is what components actually consume.
|
||||
|
||||
### 5.9 Obsidian plugin
|
||||
|
||||
`obsidian-plugin/` is a plain JavaScript community plugin; copy `main.js` and `manifest.json` into
|
||||
`<vault>/.obsidian/plugins/dragonroll-sync/` (details in its README). It signs in through
|
||||
`POST /api/user/login`, saves the 48-hour JWT token in plugin data, and does not save the password.
|
||||
The user selects a campaign from `GET /api/campaign/list`.
|
||||
|
||||
- **Import or refresh campaign notes** reads `/api/note/list` plus `/api/note/subfolder/list` and
|
||||
creates/updates Markdown files under `Dragonroll/<Campaign>/`, preserving Dragonroll's folder tree.
|
||||
- **Push active note to Dragonroll** creates a root campaign note or updates the note linked in its
|
||||
frontmatter.
|
||||
- `dragonrollId`, `dragonrollCampaign`, and `dragonrollTitle` frontmatter properties link imported
|
||||
notes. They are omitted from content sent to Dragonroll. Per-note signatures detect local edits;
|
||||
imports preserve modified local files, and push is explicit.
|
||||
|
||||
The plugin uses Obsidian's `requestUrl` helper, so the request path does not depend on browser CORS.
|
||||
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 `require`/`module.exports`; files in `services/` are shared infra, `routes/`
|
||||
are thin Express routers, `models/` one Mongoose schema per file exporting `mongoose.model(...)`.
|
||||
Every handler is `try/catch` → `{status:'error', msg:'errors.internal'}` + `console.error`.
|
||||
Route logic helpers (like `userOwnsCampaign`) are duplicated per router file today — match that
|
||||
style unless you refactor both at once.
|
||||
- **Frontend**: Vue 3 `<script setup>`; PascalCase exported functions in `services/` (`CreateWindow`,
|
||||
`GetUser`), camelCase locals; PascalCase component filenames; `kebab-case` DOM ids that services
|
||||
depend on. Both `~/` and `@/` aliases appear in imports (both resolve to `app/`) — follow whatever
|
||||
the neighbouring file uses.
|
||||
- Components talk to the API through `Server()` directly (there is no api-layer abstraction); `await`
|
||||
or `.then` both appear.
|
||||
- Code comments are mixed English and Catalan ("Moure aixo", "Programar un resizer mitjanament
|
||||
competent") — do not "translate" unrelated comments while editing.
|
||||
- No formatter: keep diffs minimal and local; the codebase is deliberately rough.
|
||||
- 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 to `app/` — use what the neighbouring file uses.
|
||||
- Components call `Server()` directly (no api layer); `await` and `.then` both 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**: add `models/X.js`, `routes/x.js` (with `userOwnsCampaign`-style ownership checks
|
||||
and the `{status,msg}` envelope), then `app.use('/api/x', require('./routes/x'))` in `src/index.js`
|
||||
**after** the `checkAuth` line if it needs auth.
|
||||
- **New API resource**: `models/X.js` + `routes/x.js` (ownership check + `{status,msg}` envelope), then `app.use('/api/x', require('./routes/x'))` in `src/index.js` **after** `checkAuth` if it needs auth.
|
||||
- **New window**: `WindowDefinitions.js` entry + `components/windows/X.vue` (§5.2) + strings in `i18n/locales/*/windows.json` (all three locales).
|
||||
- **New widget**: component in `components/viewer/widgets/{inline,display}/` + `widget_map` entry in `Marker.js`.
|
||||
- **New palette action**: `register({id, label, description, execute, isActive?})` from `~/services/ActionRegistry` (palette: `Ctrl/Cmd+K` or `/`).
|
||||
- **New theme color**: key in *both* `dark` and `light` maps in `colors.scss`, then `var(--color-<key>)`.
|
||||
|
||||
**New window**: entry in `WindowDefinitions.js` → component in `app/components/windows/` following
|
||||
§5.2 → open with `CreateWindow('type', data)` or `CreateChildWindow(parentId, 'type', data)` → strings
|
||||
in `i18n/locales/*/windows.json`.
|
||||
## 8. Known landmines (verified in code — do not "fix" silently, never make them worse)
|
||||
|
||||
**New markdown widget**: component in `app/components/viewer/widgets/{inline|display}/`, register in
|
||||
`widget_map` in `Marker.js`, consume the `content` prop.
|
||||
1. `README.md` says run `./install.sh` / `./start.sh`; **neither exists**. `frontend/README.md` says the frontend is **React**; it is Nuxt/Vue.
|
||||
2. `services/keys.js` ships the JWT secret `"putyoursecrethere"`, used in production.
|
||||
3. `POST /api/user/register` responds `{status:'ok', code: setupCode}` but `setupCode` is not in scope → caught → the first-run registration actually returns `errors.internal`. The register UI (`RegisterWindow.vue`) drives that flow; fix carefully.
|
||||
4. `POST /api/note/delete` has **no ownership check** (any authenticated user can delete any note id); the other `note.js` handlers and `folder.js` do check.
|
||||
5. `/api/user/*` is mounted before the JWT guard: new routes there are public unless they authenticate inline (`/api/discord` is also before it, but every route there is gated by `requireBot`, the shared bot-secret header). `services/middleware.js`'s `isAdmin` is imported but applied to no route.
|
||||
6. `composables/useEmitter.ts` reads `$emitter` from `useNuxtApp()` and no plugin provides it — use `~/services/Emitter`.
|
||||
7. App-wide CORS only whitelists `http://localhost:3000`; `.env.production` files are committed with internal hosts; `ecosystem.config.js` runs `npm start`, which backend/frontend do not define (PM2 is dead, compose + nginx is the real deploy).
|
||||
8. `Windows.js`: `getComponent` caches `defineAsyncComponent` per type for the whole process (restart the dev server if a new window misbehaves), `SetupHandle` attaches `document` mouse listeners per window and never removes them, and `ClearAll()` iterates `Object.keys(windows)` instead of `windows.value`.
|
||||
9. The frontend treats the JWT as the user cache: `settings` changes need `GetUserSetting`/`SetUserSetting` round-trips, the token payload goes stale.
|
||||
|
||||
**New command-palette action**: `register({id,label,description,execute,isActive?})` from
|
||||
`~/services/ActionRegistry` (see `registerCreateNoteAction` in `TopSearchBar.vue`); palette opens with
|
||||
`Ctrl/Cmd+K` or `/`.
|
||||
## 9. Ports
|
||||
|
||||
**New theme color**: add the key to *both* `dark` and `light` maps in `colors.scss`, use
|
||||
`var(--color-<key>)`.
|
||||
|
||||
## 8. Port map
|
||||
|
||||
`frontend dev :3000` · `backend :5000` (hardcoded) · MongoDB `:27017` · nginx `:3000 → 80` inside
|
||||
compose, proxying `/` → `frontend:3000`, `/api/` → `backend:5000`.
|
||||
|
||||
## 9. Known landmines (verified in code — do not "fix" silently, but never make them worse)
|
||||
|
||||
1. `README.md` tells you to run `./install.sh` and `./start.sh`; **neither script exists** in the repo.
|
||||
2. `frontend/README.md` says the frontend is **React**. It is Nuxt/Vue 3.
|
||||
3. `services/keys.js` ships a hardcoded JWT secret `"putyoursecrethere"`, used in prod.
|
||||
4. `src/index.js` sets CORS `origin: 'http://localhost:3000'` only — the production origin
|
||||
(`https://dragonroll.aranroig.com`) is not whitelisted; in production the nginx same-origin proxy
|
||||
is what hides this.
|
||||
5. `POST /api/user/register` responds `{status:'ok', code: setupCode}` but `setupCode` is not defined
|
||||
in that scope → ReferenceError → caught → the first-run registration actually returns
|
||||
`errors.internal`. Fix carefully: the register UI (`RegisterWindow.vue`) drives the first-admin flow.
|
||||
6. `POST /api/note/delete` has **no ownership check** (any authenticated user can delete any note id).
|
||||
`folder.js` and the other `note.js` handlers do check.
|
||||
7. `composables/useEmitter.ts` reads `$emitter` from `useNuxtApp()`, but **no plugin provides it** —
|
||||
always import `{ emitter }` from `~/services/Emitter` instead.
|
||||
8. `ecosystem.config.js` runs `npm start` in both apps; neither package defines a `start` script → PM2
|
||||
would fail. Compose/nginx is the real deployment path.
|
||||
9. `/api/user/*` is entirely mounted before the JWT guard (see §4); new user routes are public unless
|
||||
they call `passport.authenticate('jwt', {session:false})` inline.
|
||||
10. `checkAuth` in `src/index.js` is assigned without `const` (implicit global).
|
||||
11. `ClearAll()` in `Windows.js` iterates `Object.keys(windows)` (the ref object, not `.value`) — it
|
||||
does not behave like the name suggests.
|
||||
12. `GetWidget`/`getComponent` caches are process-global and never invalidated; new widget/window types
|
||||
need a dev-server restart if HMR misbehaves.
|
||||
13. `Windows.js` `SetupHandle` attaches `mousemove`/`mouseup` listeners on `document` for **every**
|
||||
window and never removes them; they early-return on `win.movable` but still accumulate.
|
||||
14. `Note.vue` mounts widgets with `createApp` and never unmounts them — leaked apps remain when note
|
||||
content is re-rendered.
|
||||
15. `User.js` (frontend) treats the JWT as the user cache: `settings` changes require
|
||||
`SetUserSetting`/`GetUserSetting` round-trips, the token payload goes stale.
|
||||
16. `.env.production` files (both apps) are committed and contain internal hosts.
|
||||
17. `note-created`, `note-renamed` and `folder-saved` are emitted with **no subscribers**; the sidebar's
|
||||
`handleNoteCreated` / `handleNoteRenamed` are unwired dead code (§5.6). The sidebar refreshes its
|
||||
tree only on `campaignId` change, on mount, on the manual refresh button, or on `@reload-notes`
|
||||
from `NestedNoteList.vue`.
|
||||
18. `SetShowContent` (`services/Content.js`) and `services/middleware.js`'s `isAdmin` are exported /
|
||||
imported but never used; `ContentManager.vue` never hides the workspace again once shown.
|
||||
`frontend dev :3000` · `backend :5000` (hardcoded) · MongoDB `:27017` · nginx `:3000 → 80` in compose,
|
||||
proxying `/` → frontend, `/api/` → backend.
|
||||
|
||||
Reference in New Issue
Block a user