​
Set up

1

Install dependencies

Node 20, 22, 24, or 25. The repo uses Yarn Berry — do not substitute npm, as it will not respect .yarnrc.yml.
2

Configure the environment

Set MONGO_URI, APP_URL, and one LLM provider key. Add integration credentials only for what you are working on.
3

Run it

API on http://127.0.0.1:3000, with an explorer at /explorer. For docs, run yarn dev:docs on port 3001.

​
Branch naming

Branches follow type/short-description, and reference the issue number when one exists:
Use feat/ for new capability and fix/ for corrections.

​
Commit messages

Conventional Commits, with the issue number in parentheses at the end when the change closes one:
Write the subject in the imperative and describe the effect, not the mechanism. “Release the human takeover when leaving a joined chat” is better than “update conversation controller”.

​
Before you open a PR

Fix what it reports, or run yarn lint:fix for the mechanical parts. This runs ESLint and a Prettier check across the codebase.
A clean TypeScript build is required — the build compiles the server and bundles the client.
There is no test script in package.json today, though Mocha is configured in .mocharc.json and tests live in src/__tests__. Verify changes by exercising them against a running instance, and say in your PR description how you did so.

​
Verifying your change

Prove the behavior end to end rather than reasoning from the code. For anything touching the widget, the CRM, or visitor sessions, test against a clean database with the real widget — polluted data hides duplicate-record and session bugs that only appear on a first-ever visit.

​
Opening the PR

  • Target main.
  • Describe the user-visible effect, and link the issue with Fixes #NNN.
  • Say what you did to verify it, including anything you could not test.
  • Keep the diff to one concern. A refactor bundled with a fix is two PRs.

​
Code conventions

Match the surrounding code — its naming, comment density, and idioms — rather than importing patterns from elsewhere.
  • Controllers hold routing and validation; business logic belongs in services; data access belongs in repositories.
  • Add new endpoints to the controller for that resource rather than creating a catch-all.
  • Anything shared between server and client goes in src/shared/.
  • Comment the why when a decision is non-obvious. Do not narrate the what.

​
Architecture decisions

If your change locks in a dependency, a data shape, or an upgrade path, add an ADR under docs/adr/ using 0000-template.md. Number it sequentially and never renumber — records are append-only, and a superseded decision is marked as such rather than edited away.