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

Service	Owns	Data store
backend	Auth, companies/agencies, billing & subscriptions, visitor identity graph, CRM sync, the scheduler/cron, socket fan-out	MongoDB
ms-ai	AI chat agent, AI voice agent, Nox/Knox admin assistant, knowledge-base RAG, product/booking integrations, AI cost tracking	Postgres + pgvector
ms-communication	Live chat, audio/video calls (Twilio), push (APN/FCM) and email notifications, Slack relay	MongoDB + Firestore
ms-sessions	rrweb session capture, video stitching, recording analysis, visitor presence, lead scoring	MongoDB + S3
widget	The embeddable visitor UI: chat, calls, recording capture	— (static bundle)
frontend	The dashboard SPA	— (static bundle)
desktop	The 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 (Clearbit/Apollo/HappierLeads). 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.
• 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.