NotificationCore

NotificationCore is a reusable notification foundation for backend systems.

It supports email and in-app delivery, keeps templates owned by the consuming app, and isolates provider-specific logic behind adapters.

This repository is meant to be a real backend infrastructure project, not a single-provider wrapper around email delivery.

SaaS control plane

For repo routing, boundary guidance, release checks, and machine-readable catalog surfaces across the Saazip SaaS repos, use saasctl.

Why NotificationCore

• keep notification delivery logic reusable across products
• separate templates from provider implementation
• support both sync and async delivery modes
• track attempts, delivery state, and in-app records explicitly
• model user and tenant notification preferences early
• keep the provider layer swappable from day one

Typical use cases:

• welcome and verification emails
• password reset and invite flows
• operational alerts
• in-app activity notifications
• product events that fan out to users

What NotificationCore is not

• not a campaign marketing product
• not a hard dependency on Resend
• not a place for product-specific template content

Quick start

cp .env.example .env
docker compose up -d postgres
pnpm install
pnpm dev:api
pnpm dev:dispatcher

Local services:

• API: http://localhost:3050
• Dispatcher: http://localhost:3051
• Postgres: localhost:5435

Operational defaults:

• /health and /ready stay open for probes
• /v1/* must be protected with API_KEYS in production unless you explicitly opt out
• basic request rate limiting is enabled by default for /v1/*
• requests may send x-request-id, which is echoed back or generated
• email uses the official Resend adapter when configured
• in-app notifications are persisted inside the core state

How to adopt NotificationCore

1. Use it as a library inside another backend

This is the default path.

• your app owns templates and payload shape
• NotificationCore owns delivery orchestration, preferences, and tracking
• useful when you want notifications close to product logic

2. Run the reference API and dispatcher

Use the API and dispatcher as an operational sidecar.

• your app creates notifications over HTTP
• NotificationCore owns delivery state and async execution
• useful when multiple apps should share one notification subsystem

3. Extend it in your product

• your app implements template rendering
• your app decides which events produce notifications
• NotificationCore stays generic and reusable

Repository map

apps/
  api/                 Reference API and admin surface
  dispatcher/          Async runtime for queued notification dispatch
packages/
  core/                Domain model, preferences, attempts, in-app records
  contracts/           Public Zod contracts and API schemas
  db/                  State repository and DB-oriented helpers
  sdk/                 Official client kept private in this phase
  adapters/resend/     Email provider adapter
  adapters/queueflow/  Async scheduler adapter
  observability/       JSON logs, metrics and tracing helpers
  testing/             Fixtures and builders
docs/                  Architecture, concepts, guides and operations
examples/              Reference app-level usage
docker/                Local runtime images

For contributors

1. Read this README for boundaries.
2. Read docs/README.md.
3. Read CONTRIBUTING.md before changing delivery semantics or provider boundaries.

Useful commands:

pnpm run ci
pnpm dev:api
pnpm dev:dispatcher
pnpm example:basic-app

Project docs

• Contributing guide
• Security policy
• Architecture and concepts
• API reference
• Compose with the Saazip infra suite
• Basic app example

Distribution note

NotificationCore is library-first in v1.

• the core packages and reference API are both part of the repo
• public npm publishing is intentionally deferred until the package surface stabilizes

Compatibility

• Node 24.x
• pnpm 10.33.x
• PostgreSQL 16+
• QueueFlow integration optional

Related projects

• auth-core can emit user and organization notifications
• queueflow can schedule async delivery
• eventflow can feed event-driven notifications
• webhook-core can propagate delivery events outward
• cache-core can cache preferences and template metadata

License

Apache-2.0