Skip to main content

Architecture Overview

Knock Knock is a set of cooperating services rather than a monolith. A visitor's browser talks to several of them directly (over HTTP and Socket.IO); the services talk to each other over HTTP webhooks, shared Redis, and direct REST calls. There is no shared application database — each service owns its data.

Service map​

┌────────────────────────────┐
Visitor's browser │ Customer's team │
┌──────────────────┐ │ ┌──────────┐ ┌──────────┐ │
│ widget (Vue) │ │ │ frontend │ │ desktop │ │
└───────┬──────────┘ │ │ (Vue) │ │(Electron)│ │
│ │ └────┬─────┘ └────┬─────┘ │
│ └───────┼────────────┼────────┘
│ HTTP + Socket.IO │ HTTP + Socket.IO
▼ ▼
┌───────────────────────────────────────────────────────────┐
│ backend (Express) │ ← core API, auth,
│ Nodevel framework · MongoDB · Redis · Socket.IO │ billing, CRM sync,
└───┬───────────────┬───────────────┬──────────────┬─────────┘ identity graph
│ HTTP/webhooks │ │ │
▼ ▼ ▼ ▼
┌─────────┐ ┌──────────────┐ ┌───────────┐ ┌──────────────┐
│ ms-ai │ │ms-communica- │ │ms-sessions│ │ External CRMs│
│(NestJS) │ │tion (Nodevel)│ │ (Nodevel) │ │ GHL, HubSpot │
│Postgres │ │ MongoDB │ │ MongoDB │ │ Slack, Stripe│
│pgvector │ │ Twilio/APN │ │ S3/ffmpeg │ │ Twilio, ... │
└─────────┘ └──────────────┘ └───────────┘ └──────────────┘

What each service owns​

ServiceOwnsData store
backendAuth, companies/agencies, billing & subscriptions, visitor identity graph, CRM sync, the scheduler/cron, socket fan-outMongoDB
ms-aiAI chat agent, AI voice agent, Nox/Knox admin assistant, knowledge-base RAG, product/booking integrations, AI cost trackingPostgres + pgvector
ms-communicationLive chat, audio/video calls (Twilio), push (APN/FCM) and email notifications, Slack relayMongoDB + Firestore
ms-sessionsrrweb session capture, video stitching, recording analysis, visitor presence, lead scoringMongoDB + S3
ms-voice-engineSelf-hosted Pipecat speech-to-speech voice engine (Python; no repo in this workspace, deployed from flux-deployments). Deployed but dormant — PROD serves S2S calls in direct mode, vendor-direct. See Voice EngineRedis (session registry); recordings via backend → S3
widgetThe embeddable visitor UI: chat, calls, recording capture— (static bundle)
frontendThe dashboard SPA— (static bundle)
desktopThe dashboard packaged as an Electron app—

The main flows​

1. Visitor session & recording​

  1. The customer's page loads the widget bundle, which mounts in an iframe and establishes Socket.IO connections to backend, ms-communication, and ms-sessions (keyed by company_id + a persisted user_session_id).
  2. rrweb captures DOM mutations; events stream to ms-sessions (widget:event), which buffers in Redis and flushes to disk/S3.
  3. When a session goes stale, ms-sessions enqueues a recording-analysis job (BullMQ) that rebuilds the DOM, extracts intent signals, stitches an MP4, and hands the result to ms-ai for enrichment. See Session Recording.

2. Live chat / call​

  1. The visitor opens chat or accepts a call in the widget.
  2. ms-communication routes messages (Socket.IO + Firestore) and bridges calls via Twilio; the customer's agent answers from frontend/desktop.
  3. AI chat/voice answers are produced by ms-ai (multi-model routing) and can escalate to a human.

3. Identity resolution​

  • backend runs the identity graph: it resolves a raw visitor session into a Person / PersonProfile, enriching with IP signals, fingerprint, form captures, and B2B providers (Snitcher/Apollo; Clearbit cache-only, HappierLeads removed 2026-09). See Identity Graph.

4. Nox/Knox admin assistant​

  • From the dashboard, the customer asks Nox questions or approves actions. ms-ai's knox-agent classifies intent → dispatches to a specialist sub-agent → runs tools (visitor lookups, transcripts, CRM writes) grounded in the knowledge-base RAG. See Nox Assistant.

5. CRM sync​

  • backend continuously syncs calls, chats, and identity outcomes to connected CRMs (primarily GoHighLevel, plus HubSpot/Slack/Xero) via cron jobs and a Redis-backed sync queue. See CRM Integration.

Cross-cutting conventions​

  • Three of the Node services (backend, ms-communication, ms-sessions) share the in-house Nodevel framework.
  • ms-ai is the odd one out: NestJS + TypeScript + Postgres, not Nodevel/Mongo.
  • Realtime everywhere is Socket.IO with a Redis adapter (streams adapter in ms-sessions) so it scales across pods. Company rooms are joined only by a socket whose auth.token belongs to a user who can manage that company; widgets get their own session room (see Socket room auth).
  • Tenant scoping is checked per controller (GeneralHelper.canManageCompany / canManageCompanyId, 404 on failure), and record edits on 39 backend models land in the admin Audit Trail.
  • Secrets — tenant OAuth tokens and API keys live only in the backend's credential vault (AES-256-GCM, rotatable keyring that must match across backend, schedular and ms-communication); private uploads are served via signed links. See Security & Secrets.
  • Platform switches — on/off flags a super admin flips on Admin → Settings → Feature Flags live in the backend settings collection and are read with a one-minute per-process cache (lib/platformSwitch.js), replacing several env flags.
  • Deployment is GitOps: images build in CI → pushed to a registry → FluxCD's image automation bumps the tag in flux-deployments → the cluster reconciles. See Infrastructure → Deployment.

Continue to Cross-Service Communication for the concrete endpoints and auth between services.