V3 Architecture — Single-Process Multi-User

DocHub/WhatsApp CRM/Architecture/V3 Architecture — Single-Process Multi-User

V3 replaces Docker-per-user containers with a single Node.js process managing all Baileys sockets in-process

Overview

V3 replaces the Docker-per-user container architecture (v2) with a single Node.js process that manages all users’ WhatsApp connections in-process via Baileys. This reduces per-user RAM from ~50MB (Docker + Chrome) to ~5MB (Baileys socket only) and eliminates container orchestration entirely.

Architecture Comparison

Aspect	v2	v3
Backend	Gateway + Docker containers	Single Node.js process
WhatsApp lib	Baileys in Docker per-user	Baileys in-process per-user
Per-user isolation	Docker container + PostgreSQL DB	PostgreSQL schema (user_{id})
Auth state	PostgreSQL (in slice DB)	File-based (/data/auth/{id}/)
SSE events	Gateway polls containers via HTTP	In-process EventEmitter
RAM per user	~50MB (Docker + Chrome)	~5MB (Baileys socket only)

Key Components

UserSocketManager (~900 lines)

Singleton EventEmitter managing all Baileys sockets:

connect(userId) — creates Baileys socket with file-based auth
requestPairingCode(userId, phone) — requests 8-digit pairing code
disconnect(userId) / disconnectAll() — graceful shutdown
reconnectAll() — scans /data/auth/ for saved sessions on startup

SchemaManager

Per-user PostgreSQL schemas (user_{userId}) with 17 tables each.

SSE Bridge

In-process EventEmitter from UserSocketManager to browser SSE clients. v2-compatible format with wa:catchup on connect.

Middleware

requireSession — validates session cookie
attachUserDb — scopes PoolClient to user schema
requireAdmin — validates X-Admin-Key header

File Structure

backend-v3/
  src/
    index.ts                  # Express app, routes, startup/shutdown
    UserSocketManager.ts      # Baileys socket management
    SchemaManager.ts          # Per-user PostgreSQL schemas
    sse.ts                    # SSE event bridge
    config/database.ts        # DB pools and user client helper
    middleware/userContext.ts  # Session, user DB, admin middleware
    auth/auth.ts              # Register, login, logout, /me
    billing/billing.ts        # Stripe checkout, portal, webhooks
    admin/admin.ts            # Admin API
    controllers/              # 17 controllers
    routes/                   # 15 route files
    services/                 # 6 services
    __tests__/                # 11 test suites (95 tests)

Deployment

Running on slices server (192.99.145.61) as systemd wank-backend service on port 3000.

cd backend-v3 && npx tsc
rsync -avz --exclude=node_modules backend-v3/ ubuntu@192.99.145.61:/home/ubuntu/backend-v3/
ssh ovh "cd /home/ubuntu/backend-v3 && npm install --production && sudo systemctl restart wank-backend"