New Engineer Onboarding
Welcome. This page is the orientation checklist; deeper detail lives in the linked pages.
1. Understand the shape
Read, in order:
- Architecture Overview — the service map and the five main flows.
- Cross-Service Communication — how the services actually talk.
- Data Stores — who owns what data.
That's enough to place any feature you'll touch.
2. Know the repos
All repos are siblings under one working directory (e.g. knock-knock-app/):
| Repo | Branch you'll usually work on | What it is |
|---|---|---|
backend | dev | Core Express/Mongo API (Nodevel) |
ms-ai | dev | NestJS AI service (Postgres/pgvector) |
ms-communication | dev | Chat/calls/notifications (Nodevel) |
ms-sessions | dev | Recording + presence (Nodevel) |
frontend | dev | Dashboard SPA (Vue) |
widget | dev | Embeddable visitor widget (Vue) |
desktop | dev | Electron-packaged dashboard |
flux-deployments | main | GitOps deployment manifests |
nox-knowledge-base | — | Markdown KB ingested by ms-ai |
docs-site / internal-docs | main | Customer / internal docs |
3. Run what you need
You rarely need every service. Pick the slice for your task:
- Frontend/dashboard work →
frontend+backend(+ Mongo, Redis). - Widget/visitor work →
widget+backend+ms-sessions+ms-communication. - AI / Nox work →
ms-ai(+ Postgres/pgvector, Redis) +backend.
See Local Development for exact commands, ports, and the data stores each service needs.
4. Follow the conventions
Read Conventions before opening a PR — especially the desktop is synced at release time, not per-PR rule and the forms-with-vee-validate+zod convention on the frontend.
5. Useful internal admin surfaces
| URL (per service) | What |
|---|---|
backend /admin/queues | Bull Board |
backend /admin/cron | CronMonitor job history |
backend /logs | Winston log viewer (basic auth) |
ms-ai /docs | Swagger (basic auth) |
ms-ai /admin/queues | Bull Board (basic auth) |
ms-sessions socket admin | @socket.io/admin-ui (dev only) |