shivanshsaxena03/noxwhatbot

Purpose and Runtime Topology

Jarvis is a self-hosted personal WhatsApp assistant. It combines a Node.js backend worker, WhatsApp Web connectivity, AI intent/response handling, PostgreSQL persistence, scheduled reminders, and a Next.js dashboard. Development runs the dashboard on port 3000 and worker on port 3001; production is containerized and fronted by Nginx. Key deployment files: docker-compose.yml, Dockerfile, nginx.conf, pm2.config.js.

Entry Points and Package Boundaries

The worker process is the backend control-plane entry point: packages/workers/src/server.ts, exported through packages/workers/src/index.ts. The dashboard uses Next.js App Router, rooted at apps/web/src/app/layout.tsx and apps/web/src/app/page.tsx. Shared domain contracts/constants span packages through packages/shared/src/types.ts and packages/shared/src/constants.ts.

WhatsApp Connection and Message Gate

The WhatsApp adapter is built around Baileys: packages/whatsapp/src/client.ts, packages/whatsapp/src/messageHandler.ts, and packages/whatsapp/src/qrHandler.ts. It owns session connection, QR delivery, and incoming-message intake. The critical control boundary is chat authorization: disabled chats receive no storage, processing, or replies; read-only chats are persisted but never answered; AI-enabled chats enter assistant workflows. The dashboard connection page is apps/web/src/app/connection/page.tsx.

Assistant Processing Pipeline

For AI-enabled messages, the worker routes content through the AI package: packages/ai/src/intentClassifier.ts and packages/ai/src/llmClient.ts. This is the external-service boundary to OpenRouter, configured by API key/model environment variables. Classified intents drive reminder, memory, vault, and conversational reply behavior before outbound WhatsApp sends. The central package surface is packages/ai/src/index.ts.

Persistence, Memory, and Audit State

Prisma defines the authoritative PostgreSQL data model in packages/database/prisma/schema.prisma; database access is exposed from packages/database/src/index.ts. Neon PostgreSQL is the intended managed deployment target. This layer persists authorization modes, message/history state, reminders, durable memory facts, encrypted vault records, and system/audit information. Dashboard views consume backend APIs through apps/web/src/lib/api.ts, including memory and logs pages at apps/web/src/app/memory/page.tsx and apps/web/src/app/logs/page.tsx.

Reminder Lifecycle

Natural-language reminder handling is separated into parsing and execution: packages/reminders/src/parser.ts converts message text into reminder semantics, while packages/reminders/src/scheduler.ts runs scheduled/recurring work via Node-cron. Due reminders are fetched from persistence and emitted only back to their originating authorized WhatsApp chat. Operations are exposed in apps/web/src/app/reminders/page.tsx.

Security and Dashboard Control Plane

Security primitives live in packages/security/src/crypto.ts and packages/security/src/jwt.ts; vault secrets are encrypted with AES-256-GCM using VAULT_MASTER_KEY. The vault UI is apps/web/src/app/vault/page.tsx. Dashboard-wide access/session enforcement is represented by apps/web/src/components/AuthGuard.tsx, while operators manage chat permissions at apps/web/src/app/chats/page.tsx. The web app is a management surface; the worker remains responsible for WhatsApp events, automation, and side effects.