Novu Admin Guide

This guide is for the engineers, architects, and operators who deploy, configure, secure, and extend Novu. It documents the system architecture, the self-hosting topology, the complete environment-variable reference, security posture, operational procedures, and the internals of the monorepo deeply enough to reason about — or contribute to — the platform.

For day-to-day usage (triggering workflows, the Inbox component, the CLI, providers), see the companion Novu User Guide.

Note

This guide reflects the open-source repository novuhq/novu at commit b6ab172. Novu is an open-core product: the core is MIT-licensed; the enterprise/ tree and */ee/* folders are under a commercial license. Where a capability is enterprise-only, this guide says so.

Table of Contents

1. Executive Summary
2. Architecture
3. Repository Structure
4. System Requirements
5. Deployment (Self-Hosting)
6. Configuration Reference
7. Data Stores & Schema
8. The Workflow Engine & Queues
9. Authentication & Authorization
10. Security Hardening
11. Observability & Operations
12. Module Reference (Internals)
13. Code Patterns & Conventions
14. Testing Strategy
15. Extending Novu
16. Potential Improvements
17. Quick Reference

1. Executive Summary

Novu is a notification & agent-communication infrastructure delivered as a set of cooperating Node.js services backed by MongoDB, Redis, ClickHouse, and object storage. A client triggers a workflow via the REST API; the API enqueues work onto Redis-backed BullMQ queues; a worker service executes the workflow's steps (channel sends, digests, delays) through pluggable providers; a websocket service streams in-app notifications to the embeddable Inbox in real time.

Important

All cross-channel delivery flows through the worker service, not the API. The API is a thin, authenticated front door that validates input and enqueues jobs. Scale the worker independently of the API.

2. Architecture

2.1 Runtime topology

                         ┌─────────────────────────────────────────────┐
   Browser / Inbox  ◀───▶│  ws (NestJS + socket.io)   :3002             │
                         └───────────────▲─────────────────────────────┘
                                         │ subscriber feed (Redis pub/sub)
 Your backend ──trigger──▶ ┌────────────┴───────────┐
   POST /v1/events/trigger │  api (NestJS)   :3000   │──┐
                           └────────────┬───────────┘  │ enqueue (BullMQ)
   Dashboard (React/Vite) ─▶ api        │              ▼
        :4000                           │      ┌──────────────────┐
                                        │      │  Redis (BullMQ)  │
 Inbound email (SMTP) ─▶ inbound-mail ──┤      └────────▲─────────┘
 Provider webhooks   ─▶ webhook ────────┘               │ consume
                                                ┌───────┴──────────┐
                                                │ worker (NestJS)  │──▶ Email/SMS/Push/Chat providers
                                                └───────┬──────────┘
        ┌───────────────┬───────────────┬──────────────┴───────────────┐
        ▼               ▼               ▼                               ▼
   MongoDB 8.x     ClickHouse       S3 (attachments)              In-App (▶ ws ▶ Inbox)
   (entities)      (analytics)

2.2 Services

2.3 Shared libraries

2.4 Edge workers (enterprise / Cloudflare)

The enterprise/workers/ tree contains Cloudflare Workers (Hono/Wrangler) used in Novu's hosted product:

Note

The Cloudflare workers are part of the enterprise/hosted topology. A community self-host does not need them — the in-cluster ws and worker services cover the same responsibilities.

3. Repository Structure

novu/
├── apps/                      Runtime services (deployable)
│   ├── api/                   @novu/api-service  (NestJS REST API)
│   ├── worker/                @novu/worker       (BullMQ consumers)
│   ├── ws/                    @novu/ws           (socket.io gateway)
│   ├── dashboard/             @novu/dashboard    (React + Vite SPA)
│   ├── webhook/               @novu/webhook      (inbound provider webhooks)
│   └── inbound-mail/          @novu/inbound-mail (SMTP server)
├── libs/                      Internal backend libraries
│   ├── dal/                   Mongoose schemas + repositories
│   ├── application-generic/   Shared use-cases & services
│   ├── testing/               Test harness (sessions, seed data)
│   ├── automation/            Code generators (e.g. new provider)
│   ├── notifications/         System notification templates
│   └── maily-core, maily-render, ...
├── packages/                  Published npm packages (SDKs + CLI)
│   ├── novu/                  the `novu` CLI
│   ├── framework/             @novu/framework (code-first workflows)
│   ├── js, react, nextjs,     Inbox SDKs
│   │   react-native/
│   ├── api/                   @novu/api (generated server SDK → libs/internal-sdk)
│   ├── providers/             channel providers
│   ├── shared/                shared types/DTOs/consts
│   ├── stateless/             stateless triggers
│   └── agent-toolkit/         ACI agent toolkit
├── enterprise/                Commercial-license code
│   ├── packages/              ee-ai, ee-api, ee-auth, ee-billing, ee-translation
│   └── workers/               Cloudflare edge workers
├── docker/                    Self-host (community) + local dev compose
├── playground/                Example Next.js & NestJS apps
└── nx.json, pnpm-workspace.yaml, biome.json

Tip

Build orchestration is Nx (nx run-many, nx affected). Linting/formatting is Biome (not ESLint/Prettier). The default git base branch is next. Conventional Commits are enforced (type(scope): description).

4. System Requirements

4.1 Minimum self-host footprint

The community compose runs four app containers (api, worker, ws, dashboard) plus mongodb and redis. For a small deployment, plan for ~2 vCPU / 4 GB RAM as a starting point and scale the worker first under load.

5. Deployment (Self-Hosting)

5.1 One-line community install

curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | bash

The installer (docker/community/setup.sh):

1. Checks for curl, docker, openssl, and Compose v2.
2. Downloads docker-compose.yml and .env.example.
3. Generates secrets with openssl rand -hex: JWT_SECRET (32), STORE_ENCRYPTION_KEY (16), NOVU_SECRET_KEY (32).
4. chmod 600 .env and runs docker compose up -d.

Resulting endpoints:

Dashboard : http://localhost:4000
API       : http://localhost:3000
WebSocket : http://localhost:3002

5.2 The compose stack

The community docker/community/docker-compose.yml defines:

Important

The prebuilt images are published to GitHub Container Registry under ghcr.io/novuhq/novu/<service>:<version>. Pin the version tag (e.g. 3.17.0) in production rather than tracking a moving tag, and bump deliberately.

5.3 Production deployment checklist

• [ ] Generate strong, unique JWT_SECRET, STORE_ENCRYPTION_KEY, NOVU_SECRET_KEY and store them in a secrets manager (never in the repo).
• [ ] Point MONGO_URL at a replica-set MongoDB with auth enabled.
• [ ] Use a managed/secured Redis with REDIS_PASSWORD (and TLS via REDIS_TLS if available).
• [ ] Set FRONT_BASE_URL, API_ROOT_URL, and dashboard VITE_API_HOSTNAME/VITE_WEBSOCKET_HOSTNAME to externally reachable HTTPS URLs.
• [ ] Terminate TLS at a reverse proxy in front of api, ws, and dashboard.
• [ ] Configure object storage (S3_BUCKET_NAME, S3_REGION, credentials) for attachments.
• [ ] Set IS_SELF_HOSTED=true.
• [ ] Enable rate limiting (IS_API_RATE_LIMITING_ENABLED=true) and idempotency (IS_API_IDEMPOTENCY_ENABLED=true) if desired.
• [ ] Wire health checks (/v1/health-check) into your orchestrator's liveness/readiness probes.
• [ ] Configure Sentry/New Relic if you use them.

5.4 Upgrades & rollback

• Upgrade: bump the image tags for api/worker/ws/dashboard together to the same version and docker compose up -d. The worker runs MongoDB migrations on boot when MONGO_AUTO_CREATE_INDEXES/migration scripts apply; review release notes for ClickHouse migrations (clickhouse:migrate:prod).
• Rollback: revert the image tags to the previous version. Because services share schemas, roll all four back together; avoid running mismatched versions.

Warning

Do not run a newer api against an older worker (or vice-versa) for long — they share the BullMQ job shape and MongoDB schema. Deploy all services as a set.

6. Configuration Reference

All services are configured by environment variables (parsed/validated with envalid/dotenv). The tables below list the variables found in the source.

6.1 Core

6.2 Secrets

Caution

STORE_ENCRYPTION_KEY encrypts integration credentials in the database. Rotating or losing it makes stored provider credentials unreadable. Back it up securely and rotate only with a documented re-encryption procedure.

6.3 Datastores

6.4 Worker tuning

6.5 Feature flags & behavior

6.6 Auth & integrations

6.7 Observability

Note

The dashboard is a static SPA built with Vite; its only runtime env vars are VITE_API_HOSTNAME and VITE_WEBSOCKET_HOSTNAME, which are baked at build time and must point to browser-reachable URLs.

7. Data Stores & Schema

7.1 MongoDB (primary)

All durable domain state lives in MongoDB, accessed through libs/dal using Mongoose with the repository pattern. Core entities (see packages/shared/src/entities):

Tip

When adding queries, add the matching MongoDB index in the repository. CodeRabbit's repo rules flag schema changes that need migrations and queries missing indexes — follow the repository pattern and keep reads indexed.

Migrations live in apps/api/migrations/ and run via the migration script.

7.2 Redis

Two roles: BullMQ job queues (the heart of async processing) and a cache service (often a separate Redis instance via REDIS_CACHE_SERVICE_*). The ws service also uses a Redis adapter for socket.io fan-out across instances.

7.3 ClickHouse

Analytics and high-volume activity/metrics data (charts, interaction trends, workflow-run counts) are stored in ClickHouse. Migrations are managed with clickhouse-migrations (clickhouse:migrate:local / :prod).

7.4 Object storage (S3)

Attachments and large assets go to an S3-compatible bucket. LocalStack provides S3 locally (docker/local/docker-compose.agent.yml).

8. The Workflow Engine & Queues

8.1 Lifecycle of a trigger

POST /v1/events/trigger
   └─ api: authenticate (ApiKey) → validate → upsert subscriber(s)
        └─ enqueue "trigger" job (BullMQ)
             └─ worker: parse event → fan out per subscriber/topic
                  └─ build notification jobs (one per step)
                       └─ execute steps in order:
                            ├─ channel step → resolve provider → send → record ExecutionDetails
                            ├─ digest step → hold & aggregate over window
                            ├─ delay step → schedule resume
                            └─ inApp step → persist Message → ws → <Inbox/>

8.2 BullMQ queues

The worker runs multiple queues (e.g. standard, workflow, subscriber-process, digest/unsnooze). Concurrency and lock duration are tuned with WORKER_DEFAULT_CONCURRENCY and WORKER_DEFAULT_LOCK_DURATION. Topic/broadcast fan-out is chunked (*_QUEUE_CHUNK_SIZE) to avoid flooding.

Note

Novu also supports an SQS queue backend (the SQS_DEFAULT_* vars) as an alternative to Redis/BullMQ for managed deployments. Community self-hosts use BullMQ on Redis.

8.3 Digest & delay durability

Digest and delay steps are durable: the worker persists the job state and resumes when the window/timer elapses. This survives restarts and does not hold open connections. Jobs missing required fields fail fast with Job data is missing required fields: ….

8.4 Idempotency & retries

With IS_API_IDEMPOTENCY_ENABLED, duplicate triggers carrying the same idempotency key are de-duplicated. Failed channel sends are retried per the channel's policy; exhausted retries are recorded in ExecutionDetails and surfaced in the Activity Feed.

9. Authentication & Authorization

9.1 Two auth modes

9.2 API authentication

Server-to-server requests authenticate with Authorization: ApiKey <secret-key> (environment-scoped). The Bridge sync uses the same scheme plus an HMAC signature (t=<timestamp>,v1=<sha256-hex>) for request integrity.

9.3 Subscriber (Inbox) auth

The Inbox authenticates a subscriber with the public Application Identifier plus, in production, an HMAC subscriberHash computed server-side from the Secret Key. Subscriber tokens expire per SUBSCRIBER_WIDGET_JWT_EXPIRATION_TIME.

Warning

Enable HMAC subscriber verification for the In-App integration in production. Without it, a subscriberId alone can read another user's feed.

10. Security Hardening

Novu has several first-class security mechanisms visible in the source — treat these as the baseline posture.

10.1 SSRF protection (outbound requests)

Because Novu makes outbound HTTP to user-supplied URLs (Bridge endpoints, webhook providers, provider APIs), it has a hardened outbound HTTP layer. The codebase forbids the naive one-shot validateUrlSsrf check and mandates safeOutboundRequest / safeOutboundJsonRequest (or HttpClientService with enforceSsrfProtection: true), which pins the connection to a validated IP and re-validates every redirect (defeating DNS-rebinding and redirect-based SSRF). Blocked requests raise SsrfBlockedError with reasons INVALID_URL, CREDENTIALS_IN_URL, BLOCKED_HOSTNAME, or DNS_LOOKUP_FAILED.

Caution

This rule is enforced at lint time via Biome noRestrictedImports. When writing code that makes outbound calls, never import validateUrlSsrf — use the safe-outbound helpers so SSRF protection cannot be bypassed.

10.2 Secrets at rest

Provider credentials are encrypted with STORE_ENCRYPTION_KEY before being stored in MongoDB. Keep this key in a secrets manager and back it up.

10.3 HTTP hardening

The API uses helmet for security headers, compression, CORS configured per WIDGET_BASE_URL/DOCS_BASE_URL, and rate limiting via @nestjs/throttler (and @upstash/ratelimit) when IS_API_RATE_LIMITING_ENABLED=true. Input is validated with class-validator + ajv on every DTO.

10.4 Input & filter validation

User-supplied workflow conditions are validated with strict bounds — DataFilterValidationError and TagsFilterValidationError enforce maximum group/value counts, scalar-only values, and mutually-exclusive AND/OR. This prevents pathological or abusive filter payloads.

10.5 Path traversal & file safety

The add-inbox CLI and other file-touching code reject paths outside the working directory (Access denied: Path outside working directory).

10.6 Dependency hygiene

pnpm-workspace.yaml carries an extensive overrides map pinning transitive dependencies above known-vulnerable versions, and minimumReleaseAge (4320 minutes ≈ 3 days) delays adopting brand-new releases to dodge supply-chain attacks. Renovate keeps deps current.

Important

The known issue GH #10124 (ws crash on connection reading subscriber.contextKeys.length) is a reliability/security-adjacent bug fixed in newer versions — keep the ws image and client SDKs current.

11. Observability & Operations

11.1 Health checks

Every service exposes GET /v1/health-check (used by the compose healthchecks and suitable for k8s liveness/readiness). Built with @nestjs/terminus and @godaddy/terminus.

curl -fsS http://localhost:3000/v1/health-check

{ "status": "ok", "info": { "mongo": { "status": "up" }, "redis": { "status": "up" } } }

11.2 Logging

Structured logging uses Pino (PinoLogger from @novu/application-generic is mandated over NestJS's default Logger — enforced by Biome). Container logs are JSON with rotation (max-size: 50m, max-file: 5).

11.3 Metrics & tracing

• Sentry (SENTRY_DSN) for error tracking across all services.
• New Relic (NEW_RELIC_*) for APM.
• OpenTelemetry (ENABLE_OTEL) for traces/metrics export.
• Worker emits active-jobs metrics (active-jobs-metric.service.ts).

11.4 Routine operations

11.5 Scaling guidance

• The worker is the throughput bottleneck for delivery — scale it horizontally first; BullMQ distributes jobs across instances safely (atomic locks).
• The ws service scales horizontally with the Redis socket.io adapter.
• The api is stateless behind a load balancer.
• Size MongoDB and Redis for peak trigger volume; digests/delays add long-lived job state to Redis.

12. Module Reference (Internals)

The repository contains 212 high-priority module groups. The highest-signal areas for an operator/contributor:

12.1 API resource families (REST)

The API is large and versioned (v1 and v2 paths). Because routes are NestJS decorators (not all captured by static extraction), the authoritative endpoint reference is the generated OpenAPI spec — the API generates it via @nestjs/swagger (exportOpenAPIJSON.ts / generate:swagger) and serves Swagger UI. Major resource families:

• /v1/events/trigger — trigger workflows (single, bulk, topic, broadcast); DELETE to cancel by transaction id.
• /v1/subscribers — subscriber CRUD, credentials, preferences.
• /v1/workflows (v1) and v2 equivalents — workflow management.
• /v1/integrations — provider configuration.
• /v1/topics — topic management and subscriptions.
• /v1/inbox — Inbox notifications, counts, preferences.
• /v1/bridge/sync — register code-defined workflows from a Bridge URL.
• /v1/agents/* — ACI agent management & bridge URLs.
• /v1/health-check — health.

Tip

To get the exact, version-matched endpoint list for your deployment, fetch the OpenAPI document from your running API (the dashboard's API reference and docs.novu.co/api-reference are generated from it).

13. Code Patterns & Conventions

• CQRS / use-case pattern. API controllers stay thin; business logic lives in commands (*.command.ts) and use-cases (*.usecase.ts). A Biome plugin enforces command-session exclusion; DTOs have dedicated property-optionality plugins.
• Repository pattern for all MongoDB access (libs/dal).
• Provider interface. Every provider implements the standard channel interface (base.provider.ts); a generator (libs/automation, pnpm generate:provider) scaffolds new ones.
• Biome, not ESLint/Prettier. Formatting (2-space, single quotes, semicolons, 120 col) and linting are unified under Biome 2.x with project-specific noRestrictedImports rules (PinoLogger over Logger; safe-outbound over validateUrlSsrf; root-package imports only).
• Nx workspace. nx run-many / nx affected; build caching via Nx Cloud; independent per-project versioning with Conventional Commits.
• Strict import boundaries. Packages must be imported from their root entry (e.g. @novu/api, not @novu/api/src).
• Generators. hygen templates (_templates/) scaffold new modules/use-cases (pnpm g:module, pnpm g:usecase).

14. Testing Strategy

Run, e.g.:

pnpm --filter @novu/api-service test       # API unit
pnpm test:providers                        # all providers
pnpm --filter @novu/dashboard test:e2e     # dashboard Playwright

Note

A stop-only lint guard prevents committing .only in test files. E2E API runs require NODE_OPTIONS=--no-experimental-strip-types (Node 22 quirk) and spin up MongoDB/Redis (LocalStack for S3).

15. Extending Novu

15.1 Add a new provider

1. cd libs/automation && pnpm generate:provider (or pnpm generate:provider from root) — scaffolds the provider folder.
2. Implement the standard channel interface in packages/providers/src/lib/<channel>/<name>.
3. Add credentials metadata so the dashboard can render the integration form.
4. Add a handler in libs/application-generic/src/factories/<channel>/handlers.
5. Add provider tests; run pnpm test:providers.

Tip

The community frequently requests new providers (open issues include WeChat/Weixin #4493, LINE #11048, Google Chat #1478, ValueFirst SMS #10919). A new provider is a well-scoped first contribution.

15.2 Add an API feature

Use the generators (pnpm g:module, pnpm g:usecase) to scaffold a NestJS module + use-case + command following the CQRS pattern, add a repository in libs/dal if it needs persistence (with indexes + migration), and add e2e coverage under apps/api/e2e.

15.3 Code-defined steps (step publish)

novu step publish bundles step handlers and deploys them; the enterprise step-resolver Cloudflare worker can execute them at the edge in a dispatch namespace (HMAC-secured via STEP_RESOLVER_HMAC_SECRET).

16. Potential Improvements

Observations from the source, useful for operators and contributors:

• API endpoint discoverability. The REST surface is large and versioned (v1/v2 coexist, e.g. topics-v1/topics-v2, workflows-v1/workflows-v2, layouts-v1/layouts-v2). Static analysis captures only a fraction of routes; rely on the generated OpenAPI. Consolidating v1→v2 over time would reduce surface area.
• Open issues to track for self-hosters: community org-switching in self-hosted mode (#11356), FCM rich push (#9489), preferences-by-context (#11114), and NovuModule.registerAsync silently ignoring controllerDecorators in @novu/framework (#11009). Watch these if you depend on those features.
• Config sprawl. ~100+ environment variables span services; a single documented .env.example per service (the community installer fetches one at runtime) plus a validated schema dump would aid operators. envalid already validates — surfacing the schema would help.
• Mismatched-version risk. Because api/worker/ws share schema and job shapes, version drift is a real operational hazard; pin and deploy as a set.
• ClickHouse is an extra moving part. Analytics depends on ClickHouse; small self-hosts that don't need charts could benefit from a documented "no-analytics" mode.

17. Quick Reference

17.1 Services & ports

17.2 Critical env vars

17.3 Common commands

# Self-host
curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | bash
docker compose up -d
docker compose logs -f worker

# Local development (from source)
pnpm install
pnpm start:api ; pnpm start:worker ; pnpm start:ws ; pnpm start:dashboard
# or all at once:
pnpm dev:portless        # mprocs-managed multi-process dev

# Build
pnpm build                       # everything (Nx)
pnpm build:api                   # one service
nx affected -t build             # only changed projects

17.4 Key technologies