Local Development

Each repo runs independently. Start only the services your task needs (see the slices in New Engineer).

Ports & env

Ports below are the observed defaults; the source of truth is each repo's .env and config. Always copy the repo's example env and fill in secrets before starting.

Shared data stores

Store	Used by	Local note
MongoDB	backend, ms-communication, ms-sessions	Use mongo:7.0 — MongoDB 8.0 segfaults on some kernels.
Redis	backend, ms-communication, ms-sessions, ms-ai	One instance is fine locally; the cluster splits per service.
Postgres + pgvector	ms-ai	Provided by ms-ai/docker-compose.yml (Postgres 17 + pgvector).
S3	backend, ms-sessions	Real bucket or a local S3-compatible store; FILE_STORAGE=local skips S3.

Node services

All Node services target Node 20+ (containers run Node 22).

backend (Express / Nodevel)

cd backend
npm install
npm run dev        # nodemon

• Default app port 8080 (container exposes 8888).
• Needs MongoDB + Redis. Set MS_AI_URL, MS_SESSION_URL, MS_COMMUNICATION_URL and MS_AI_SECRET_TOKEN to reach peers.
• SERVICE_CRON=true enables the scheduler (cron jobs). Leave it off for a normal API dev loop; the production scheduler runs as a separate pod.

ms-ai (NestJS)

cd ms-ai
npm install
docker compose up -d        # Postgres(+pgvector) + Redis
npm run migration:run       # apply TypeORM migrations
npm run start:dev           # watch mode

• Default port 3000.
• Needs ANTHROPIC_API_KEY / OPENAI_API_KEY (and optionally MISTRAL_API_KEY, COHERE_API_KEY for rerank, ELEVENLABS_API_KEY for voice).
• Migrations are not run in the container entrypoint — run them yourself (or via CI) to avoid races across replicas.

ms-communication / ms-sessions (Nodevel)

cd ms-sessions   # or ms-communication
npm install
npm run dev

• ms-sessions: app port 3003. Recording worker runs separately: npm run dev:recording-worker.
• ms-communication: app port 8080. Needs Twilio / APN / Firebase / Slack creds for the features that use them (mock or leave unset to disable).
• Both need MongoDB + Redis.

Client apps

frontend (Vue dashboard)

cd frontend
npm install
npm run dev        # Vite dev server on :4000

Point it at your local backend via src/config/env.config.js / VITE_* env.

widget (Vue, embeddable)

cd widget
npm install
npm run dev        # Vite dev server

The widget connects to backend / ms-communication / ms-sessions sockets keyed by company_id + user_session_id. For end-to-end testing, load it against a test company in your local backend.

desktop (Electron)

cd desktop
npm install
npm run dev        # Vite + Electron, hot reload
npm run dev:next   # white-label ("Next Level AI") variant

Desktop wraps the same dashboard code as frontend. Do not mirror frontend edits into desktop per-PR — desktop is synced at release time (see Conventions).

Putting it together

A typical "visitor end-to-end" loop:

1. Mongo + Redis up.
2. backend (SERVICE_CRON=false), ms-sessions (+ recording worker), ms-communication.
3. widget pointed at local backend.
4. Optionally frontend to watch the session live and answer chats/calls.

Add ms-ai (+ Postgres) only when you need AI chat/voice or Nox.