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.

Migrations (ms-ai)​

ms-ai migrations are not auto-run by the container entrypoint (avoids races across replicas). Run npm run migration:run explicitly or via CI.

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.