Conventions
Things that will trip you up if you don't know them.
Repos & branches
- Service repos develop on
dev;flux-deploymentsand the docs sites onmain. - All repos are siblings in one parent directory — relative paths like
../backend(used by the docs sync script and some tooling) assume this layout.
Desktop is synced at release time, not per-PR
desktop is the frontend dashboard wrapped in Electron. Do not copy
frontend changes into desktop as part of a frontend PR. The desktop renderer is
synced from frontend at major release checkpoints to keep desktop builds stable
and CI cheap. White-label desktop builds (build:next / publish:next) are a
build-flag variant, not a code fork.
Frontend forms: vee-validate + zod
Build forms with vee-validate + @vee-validate/zod, not hand-rolled
reactive() objects. Use the wrappers in frontend/src/components/form/
(FormInput, FormSelect, FormPhone, …) which wrap useField(). Define the
schema with toTypedSchema(z.object({...})) and drive submission with
useForm().
Frontend data layer: repositories + TanStack Query
API calls live as plain async functions in frontend/src/repositories/<area>/.
TanStack Vue Query wraps them, with keys from @lukemorales/query-key-factory
(queryKeys.js per area). Don't call axios directly from components — add a
repository function.
The Nodevel services share a framework
backend, ms-communication, and ms-sessions boot through the in-house
Nodevel framework (core/ + app/hooks.js +
app/routes/api.js). New routes/services/models follow that structure, not bare
Express. ms-ai is not Nodevel — it's standard NestJS.
MongoDB version
Run mongo:7.0 locally. 8.0 segfaults on some kernels.
Scheduler / cron
Cron lives in backend but runs as a separate scheduler pod in production
(SERVICE_CRON=true) so jobs fire exactly once. Don't enable cron on every local
backend instance. Interval jobs are staggered by a fixed per-job offset and fire on
the wall clock, so don't assume a 15-minute job runs at :00/:15/:30/:45.
Secrets & switches
- Tenant OAuth tokens and API keys go in the credential vault
(
resolveOnce('app.services.CredentialVault').get/set/remove(owner, provider)), never on a company/agency document, and never in a response or log. Secrets callers present to us (API keys, login codes) are stored hashed (lib/secretHash) and shown once. Any new field holding SecretCrypto blobs must be added tolib/reencryptSecrets.jsROOTSso key rotation covers it. - New private upload folders go in
lib/privateFiles.js; hand out signed links (lib/fileLink.js), not public URLs. - An on/off a super admin should flip without a deploy is a platform switch:
a
settingsrow read withswitchOn(key)(lib/platformSwitch.js, one-minute cache) and a toggle on Admin → Settings → Feature Flags — not a new env var. - New
/admin/...endpoints are closed to admin staff until their path prefix is added to a section inlib/adminSections.js(and the frontend mirror).
See Security & Secrets.
Boot order (backend)
app.loadService('scheduler', …) is the last statement of boot() in
backend/app/hooks.js. SchedulerService constructs all jobs and starts
ticking in its constructor, so a job whose constructor touches a global loaded
later crashes the schedular pod only — API pods never construct jobs. Keep it
last, keep eslint.config.mjs globals in step with hooks.js, and reproduce
schedular-only crashes locally with SERVICE_CRON=true.
Shared models move in lock-step
backend, ms-communication, and ms-sessions each declare copies of shared
Mongoose models (CompanyModel, UserSessionModel, ChatModel,
ServiceRoomModel, InboundOutboundCallModel, CompanyWebsiteModel, …). A
field declared in one and not another is silently dropped by strict mode on
write; an index that differs throws IndexOptionsConflict at boot. Use the
models sync CLI in backend before pushing:
node run models:status [Model] # exit 1 on drift — run before pushing
node run models:sync [Model] # per-file b/s/m/d/q prompts
node run models:help
The same trap exists inside one service: a backend model that doesn't declare a
field another service writes (the sweepers' recording_status / skipped_reason
on SessionFileModel, 2026-09) drops every $set of it silently — only
updated_at changes. Declare the field (no default/index if another service
owns them).
It compares compiled schema paths (comment/index/order differences report as "same fields, file differs"), verifies every write by loading the model and restores it if it stops booting, and never auto-merges type conflicts.
One-shot data fixes and long sweeps
There is no shell on prod pods. A data fix ships as an api-key /migrations/*
endpoint plus a super-admin /admin/* wrapper and a MigrationPanel card
(dry-run first, then Apply) — never a scripts/ file, which is local-dev only.
The endpoint starts a background job and returns its id; the card polls
…/jobs/:job_id. Lessons from the 2026-09 identity sweeps, each learned from a
prod connection N to <ip> timed out:
- Never cursor a whole large collection without an index to ride. Walk it
tenant by tenant or in fixed time slices (the device-claim backfill
uses one-hour slices), page by
_id, and setmaxTimeMSon every query. - Start from the small side of a join (e.g. the few thousand verified fingerprints, not every anonymous session).
- Catch per-tenant failures and report them (
companies_failed,scan_error) instead of losing the stats of a mostly-finished run. - Every field an
updateManyfilters on must lead an index; check it in the dry run and refuse Apply while indexes are still building after a deploy (personMergeindexes_missing). - Build a replacement unique index before dropping the old one.
Once a one-shot has run in production, delete its endpoint and its card
(done for every pre-2026-10-15 one-shot and again on 2026-11-16, 44820dc7e /
5e191564); recurring tools stay.
List endpoints
Backend list responses are clamped to MAX_LIST_LIMIT (1000) by the validator,
and a filter rule written limit: 'limit' with no default now means 1000, not
"everything". Give list schemas an explicit default (limit:50), paginate on
the client, and expect X-Result-Limit-Capped when the server overrode a page
size. Controllers that need "caller sent no limit" read limit_defaulted.
Tests (backend)
backend/test/index.test.js must require a spec or it never runs. Mocha
requires every spec before running any test, so a module-scope global
assignment (global.resolveOnce, Config, app, …) is last-require-wins and
breaks other specs only at run time. Take globals in before()/after() inside
the describe that needs them, and spread-merge Config rather than replacing
it. Don't pin fixtures to an absolute date when the code bills or counts up to
"now" — inject now (e.g. AgentKLinkedInRenewalJob.run(now)). The suite was
brought to 0 failures on 2026-09-17 (1993 passing); keep it there.
Migrations (ms-ai)
ms-ai migrations are not auto-run by the container entrypoint (avoids races
across replicas). Run npm run migration:run locally; production runs
npm run migration:run:prod (compiled runner) as a deploy step.
Code style
- Keep comments minimal — no verbose justification comments. Put the "why" in the PR/commit, not inline.
- Match the surrounding file's idioms (naming, structure, comment density).
Docs
- Customer-facing changes →
docs-site. Implementation detail → here (internal-docs). - Run
scripts/list-doc-changes.shbefore a docs pass to see what changed in each service since the last update;--record-syncto stamp the new baseline.