Files
dragonroll/AGENTS.md
Aran Roig 1fab8ce20d
All checks were successful
Build and Deploy Nuxt / build (push) Successful in 53s
Bug fix
2026-10-11 22:38:59 +02:00

475 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
## 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:
- `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.
There is **no** database seeding, no ORM migrations, no test suite, no linter/formatter config, no
Pinia/Vuex, and no Vue Router pages (see §5.1 — the UI is a window manager, not routed pages).
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`.
## 2. Root layout
```
dragonroll/
├── backend/ Express API (CommonJS, entry: src/index.js)
├── frontend/ Nuxt 4 app (entry: app/app.vue)
├── 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
├── package.json root: only `concurrently`, used by `npm run dev`
└── README.md install/run instructions are STALE (see §9)
```
## 3. 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
```
There is no `start` script in either package, no test command, and no lint command.
Verification = run the dev server and exercise the flow (`/api/test` returns a JSON hello).
### Environment files
| 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** |
`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.
## 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
├── routes/ user.js campaign.js note.js folder.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>`
└── 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
`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`.
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`.
### Response convention
Every endpoint returns HTTP 200 with a JSON envelope; there is almost no real status-code usage:
```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".
### Authorization model
Single-tenant per user: a campaign belongs to `createdBy`, everything else hangs off a campaign.
`note.js` and `folder.js` define a local helper:
```js
async function userOwnsCampaign(campaignId, userId) { ... } // duplicated in both files
```
Ownership is enforced per handler. `settings`, `color`, `description` and `User.settings` are schemaless
`Object`/free-form fields.
### Data model
```
User ──< Campaign ──< Note ──?> Folder ──?> Folder (parentFolder, self-ref)
└───────< Folder
```
| 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) |
| `Note` | `models/Note.js` | `title`, `content` (markdown source string), `campaign*` → Campaign, `folder` → Folder (null = root), `date` |
| `Folder` | `models/Folder.js` | `name*`, `campaign*` → Campaign, `parentFolder` → Folder (null = root), `date` |
`*` = required. Notes and folders are ordered by `date: -1` everywhere.
### 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)
`GET /api/note/subfolder/list?campaign=&folder=` → `{status:'ok', subfolders, notes}`
`POST /api/note/create` — `{title*,content,campaign*,folder?}` (folder validated against campaign)
`POST /api/note/update` — `{id*, title?, content?, folder?}` — partial, ownership checked
`POST /api/note/delete` — `{id}` — **no ownership check** (§9)
`GET /api/folder/list?campaign=` → `{status:'ok',folders}`
`POST /api/folder/create` — `{name*,campaign*}`
`POST /api/folder/rename` — `{id*,name*}`
`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.
## 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}, 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 It is not a routed app
There is no `app/pages/`. `app/app.vue` renders a fixed shell of managers. "Screens" are either:
- **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.
Boot sequence (`app.vue` → `start()`):
```
GetUser() (JWT in localStorage, un-expired)?
├─ yes → RestoreCampaign() (localStorage.selectedCampaignId) → on failure open 'main_menu'
└─ no → HasAdmin() ? open 'login' : open 'register' {firstTime:true}
```
### 5.2 The window system (most important thing to understand)
`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/Windows.js` is the runtime. Module-level state: `windows = ref([])`, auto-incrementing
`currentId`, `currentIndex` z-index counter. Key exports:
`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.
Contract a window component must fulfil (copy `ExampleWindow.vue`):
```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>
```
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`.
`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.
### 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). `SetShowContent` is exported but unused — `ContentManager.vue` sets it from a `watch(Campaign)` and never turns it back off |
| `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) |
| `title-updated` | `{key,title}` | `Note.vue`, `NoteContainer.vue` |
| `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.
## 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.
## 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 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`.
**New markdown widget**: component in `app/components/viewer/widgets/{inline|display}/`, register in
`widget_map` in `Marker.js`, consume the `content` prop.
**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 `/`.
**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.