# shivanshsaxena03/noxwhatbot architecture

> Architecture diagram of the GitHub repository shivanshsaxena03/noxwhatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivanshsaxena03/noxwhatbot
- Repository: https://github.com/shivanshsaxena03/noxwhatbot

## Overview

#### 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.

Main entry points: [`packages/database/src/index.ts`](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/database/src/index.ts) (Database Access), [`packages/workers/src/server.ts`](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/workers/src/server.ts) (Worker Server), [`packages/ai/src/intentClassifier.ts`](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/ai/src/intentClassifier.ts) (Intent Classifier), [`packages/whatsapp/src/client.ts`](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/client.ts) (Baileys WhatsApp Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_worker["Backend Worker"]
  node_worker_server["Worker Server<br/>Node.js entry point<br/>[server.ts]"]
  node_whatsapp_client["Baileys WhatsApp Client<br/>WhatsApp adapter<br/>[client.ts]"]
  node_message_gate["Message Authorization Gate<br/>message handler<br/>[messageHandler.ts]"]
  node_qr_handler["QR Handler<br/>connection handler<br/>[qrHandler.ts]"]
  node_reminder_scheduler["Reminder Scheduler<br/>cron worker<br/>[scheduler.ts]"]
end

subgraph group_dashboard["Dashboard"]
  node_web["Next.js Dashboard<br/>web app<br/>[layout.tsx]"]
  node_auth_guard["Dashboard Auth Guard<br/>session enforcement<br/>[AuthGuard.tsx]"]
  node_dashboard_api["Dashboard API Client<br/>backend client<br/>[api.ts]"]
  node_connection_ui["Connection UI<br/>dashboard page<br/>[page.tsx]"]
  node_operations_ui["Operations Views<br/>dashboard pages<br/>[page.tsx]"]
end

subgraph group_domain["Domain Services"]
  node_ai_intent["Intent Classifier<br/>AI routing"]
  node_openrouter{{"OpenRouter<br/>external LLM<br/>[llmClient.ts]"}}
  node_reminder_parser["Reminder Parser<br/>NL parser<br/>[parser.ts]"]
  node_security["Vault Crypto<br/>security service<br/>[crypto.ts]"]
  node_database[("Database Access<br/>Prisma data layer<br/>[index.ts]")]
  node_shared_contracts["Shared Contracts<br/>domain contracts<br/>[types.ts]"]
end

node_nginx{{"Nginx<br/>reverse proxy<br/>[nginx.conf]"}}
node_postgres[("Neon PostgreSQL<br/>managed database<br/>[schema.prisma]")]

node_nginx -->|"serves"| node_web
node_nginx -->|"proxies API"| node_worker_server
node_web -->|"enforces access"| node_auth_guard
node_auth_guard -->|"authorizes"| node_dashboard_api
node_connection_ui -->|"connection state"| node_dashboard_api
node_operations_ui -->|"management operations"| node_dashboard_api
node_dashboard_api -->|"backend requests"| node_worker_server
node_worker_server -->|"controls"| node_whatsapp_client
node_whatsapp_client -->|"connection QR"| node_qr_handler
node_whatsapp_client -->|"incoming messages"| node_message_gate
node_message_gate -->|"authorization and history"| node_database
node_message_gate -->|"AI-enabled chats"| node_ai_intent
node_ai_intent -->|"inference"| node_openrouter
node_ai_intent -->|"reminder intent"| node_reminder_parser
node_reminder_parser -->|"stores reminder"| node_database
node_ai_intent -->|"memory, vault, audit"| node_database
node_database -->|"encrypts vault records"| node_security
node_database -->|"persists via Prisma"| node_postgres
node_reminder_scheduler -->|"fetches due reminders"| node_database
node_reminder_scheduler -->|"sends to authorized origin chat"| node_whatsapp_client
node_worker_server -->|"runs automation"| node_reminder_scheduler
node_shared_contracts -.->|"shared types"| node_worker_server
node_shared_contracts -.->|"shared types"| node_web

click node_nginx "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/nginx.conf"
click node_web "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/layout.tsx"
click node_auth_guard "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/components/AuthGuard.tsx"
click node_dashboard_api "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/lib/api.ts"
click node_connection_ui "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/connection/page.tsx"
click node_operations_ui "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/chats/page.tsx"
click node_worker_server "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/workers/src/server.ts"
click node_whatsapp_client "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/client.ts"
click node_message_gate "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/messageHandler.ts"
click node_qr_handler "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/qrHandler.ts"
click node_ai_intent "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/ai/src/intentClassifier.ts"
click node_openrouter "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/ai/src/llmClient.ts"
click node_reminder_parser "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/reminders/src/parser.ts"
click node_reminder_scheduler "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/reminders/src/scheduler.ts"
click node_security "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/security/src/crypto.ts"
click node_database "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/database/src/index.ts"
click node_postgres "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/database/prisma/schema.prisma"
click node_shared_contracts "https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/shared/src/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_worker_server,node_whatsapp_client,node_message_gate,node_qr_handler,node_reminder_scheduler toneBlue
class node_web,node_auth_guard,node_dashboard_api,node_connection_ui,node_operations_ui toneAmber
class node_ai_intent,node_openrouter,node_reminder_parser,node_security,node_database,node_shared_contracts toneMint
class node_nginx,node_postgres toneNeutral
```

## Components

### Backend Worker

WhatsApp event and automation control plane.

- [Worker Server](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/workers/src/server.ts): Node.js entry point · Backend API and workflow control plane. · `packages/workers/src/server.ts`
- [Baileys WhatsApp Client](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/client.ts): WhatsApp adapter · Owns session connection and inbound/outbound transport. · `packages/whatsapp/src/client.ts`
- [Message Authorization Gate](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/messageHandler.ts): message handler · Disabled chats stop; read-only chats persist without replies. · `packages/whatsapp/src/messageHandler.ts`
- [QR Handler](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/whatsapp/src/qrHandler.ts): connection handler · `packages/whatsapp/src/qrHandler.ts`
- [Reminder Scheduler](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/reminders/src/scheduler.ts): cron worker · Runs due and recurring reminder work. · `packages/reminders/src/scheduler.ts`

### Dashboard

Next.js management surface.

- [Next.js Dashboard](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/layout.tsx): web app · Operator management UI. · `apps/web/src/app/layout.tsx`
- [Dashboard Auth Guard](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/components/AuthGuard.tsx): session enforcement · `apps/web/src/components/AuthGuard.tsx`
- [Dashboard API Client](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/lib/api.ts): backend client · `apps/web/src/lib/api.ts`
- [Connection UI](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/connection/page.tsx): dashboard page · Displays WhatsApp connection and QR state. · `apps/web/src/app/connection/page.tsx`
- [Operations Views](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/apps/web/src/app/chats/page.tsx): dashboard pages · Chats, reminders, memory, vault, and logs management. · `apps/web/src/app/chats/page.tsx`

### Domain Services

- [Intent Classifier](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/ai/src/intentClassifier.ts): AI routing · Classifies AI-enabled message intent. · `packages/ai/src/intentClassifier.ts`
- [OpenRouter](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/ai/src/llmClient.ts): external LLM · Model inference boundary. · `packages/ai/src/llmClient.ts`
- [Reminder Parser](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/reminders/src/parser.ts): NL parser · Converts message text into reminder semantics. · `packages/reminders/src/parser.ts`
- [Vault Crypto](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/security/src/crypto.ts): security service · AES-256-GCM encryption for vault records. · `packages/security/src/crypto.ts`
- [Database Access](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/database/src/index.ts): Prisma data layer · Authoritative state for chats, history, reminders, memory, vault, and audit data. · `packages/database/src/index.ts`
- [Shared Contracts](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/shared/src/types.ts): domain contracts · Shared types and constants across packages. · `packages/shared/src/types.ts`

### Other components

- [Nginx](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/nginx.conf): reverse proxy · Fronts the production containers. · `nginx.conf`
- [Neon PostgreSQL](https://github.com/shivanshsaxena03/noxwhatbot/blob/main/packages/database/prisma/schema.prisma): managed database · `packages/database/prisma/schema.prisma`

## Connections

- Nginx → Next.js Dashboard: serves
- Nginx → Worker Server: proxies API
- Next.js Dashboard → Dashboard Auth Guard: enforces access
- Dashboard Auth Guard → Dashboard API Client: authorizes
- Connection UI → Dashboard API Client: connection state
- Operations Views → Dashboard API Client: management operations
- Dashboard API Client → Worker Server: backend requests
- Worker Server → Baileys WhatsApp Client: controls
- Baileys WhatsApp Client → QR Handler: connection QR
- Baileys WhatsApp Client → Message Authorization Gate: incoming messages
- Message Authorization Gate → Database Access: authorization and history
- Message Authorization Gate → Intent Classifier: AI-enabled chats
- Intent Classifier → OpenRouter: inference
- Intent Classifier → Reminder Parser: reminder intent
- Reminder Parser → Database Access: stores reminder
- Intent Classifier → Database Access: memory, vault, audit
- Database Access → Vault Crypto: encrypts vault records
- Database Access → Neon PostgreSQL: persists via Prisma
- Reminder Scheduler → Database Access: fetches due reminders
- Reminder Scheduler → Baileys WhatsApp Client: sends to authorized origin chat
- Worker Server → Reminder Scheduler: runs automation
- Shared Contracts → Worker Server: shared types
- Shared Contracts → Next.js Dashboard: shared types