Skip to main content

Conventions

Things that will trip you up if you don't know them.

Repos & branches​

  • Service repos develop on dev; flux-deployments and the docs sites on main.
  • 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 to lib/reencryptSecrets.js ROOTS so 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 settings row read with switchOn(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 in lib/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 set maxTimeMS on 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 updateMany filters on must lead an index; check it in the dry run and refuse Apply while indexes are still building after a deploy (personMerge indexes_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.sh before a docs pass to see what changed in each service since the last update; --record-sync to stamp the new baseline.