Concepts
Architecture
The service at the centre, the three required seams, the optional seams, and how implementations are injected.
The library is one service class surrounded by interfaces it does not implement. The service owns the orchestration: it records a notification, decides when it is due, generates its context, asks an adapter to deliver it and writes the outcome back. Everything that touches a database, a file, a mail server or a message broker sits behind a seam: an abstract interface with a small contract, implemented by a separate package or by your own code.
The service is NotificationService in vintasend.services.notification_service. Seams are abstract base classes under vintasend.services, one package per seam, each with a base.py and a stubs/ directory holding a working fake.
The service is the VintaSend class, built through VintaSendFactory from the vintasend package. Seams are TypeScript interfaces under src/services, one folder per seam, and every module is generic over one NotificationTypeConfig described below.
The required seams
Without one of each, the service cannot record, render or deliver anything.
| Seam | Responsibility | Base |
|---|---|---|
| Backend | Persist, query and update notification records; mark them sent, failed, read or cancelled; store the context used | BaseNotificationBackend |
| Adapter | Deliver one rendered notification over one channel (email, SMS, push, in-app) | BaseNotificationAdapter |
| Template renderer | Turn a template reference plus a context into a sendable body (and subject, for email) | BaseNotificationTemplateRenderer |
An adapter owns a renderer: the service hands the adapter a notification and a context, and the adapter asks its renderer for the body before delivering it. One adapter serves one notification type, and the service refuses two adapters that declare the same type.
from vintasend.services.notification_backends.base import BaseNotificationBackend
from vintasend.services.notification_adapters.base import BaseNotificationAdapter
from vintasend.services.notification_template_renderers.base import BaseNotificationTemplateRendererAdapters are generic over the other two, BaseNotificationAdapter(Generic[B, T], ABC), where B is the backend type and T the renderer type. Each base class declares its contract with @abstractmethod, so a subclass missing a method fails with TypeError the moment it is constructed, not the first time the method is called. Raising DuplicateNotificationAdapterError is how the service rejects two adapters of the same type.
import type {
BaseNotificationBackend,
BaseNotificationAdapter,
BaseNotificationTemplateRenderer,
} from 'vintasend';These are interfaces, not classes, so an implementation is any object with the right shape. An adapter carries a key (its identifier, stored on the record as the adapter used), a notificationType and an enqueueNotifications flag; the flag marks it as a background adapter whose delivery runs in a worker. The factory throws if two adapters declare the same notificationType.
The optional seams
Each optional seam gates a feature. No default ships, so leaving one unconfigured turns the feature off.
| Seam | Unset means |
|---|---|
| Attachment manager | Attachments are unsupported. The service never injects one into the backend, so a notification created with attachments has nowhere to store them |
| Queue service | A background adapter has nothing to enqueue to. sendsend logs the problem and skips that adapter (raises when configured to) |
| Replication queue service | Queued replication to additional backends falls back to inline replication |
| Git commit SHA provider | No commit SHA is ever resolved or written; the field stays empty on every record |
Each has a guide: attachments, background sending, multiple backends and git commit SHA tracking.
In Python these are BaseAttachmentManager, BaseNotificationQueueService, BaseNotificationReplicationQueueService and BaseGitCommitShaProvider, each in its own package under vintasend.services. The queue service is the one optional seam that does not fail silently: with a background adapter configured and no queue service, send() raises NotificationQueueServiceMissingError when raise_on_failed_send=True, and logs an error otherwise. A queue service that is configured but cannot be imported or instantiated raises NotificationQueueServiceResolutionError at construction time rather than being treated as unset.
In TypeScript these are BaseAttachmentManager, BaseNotificationQueueService, BaseNotificationReplicationQueueService and BaseGitCommitShaProvider. There is a fifth seam with no Python counterpart: the logger. BaseLogger has info, error and warn, each taking a LogMessage built with the log tagged template rather than a plain string, so a logger only ever receives ids, counts, labels, timestamps and reduced errors. It is required, not optional; vintasend-winston is the official implementation. Python has no logger seam because it writes to the standard logging module.
How implementations are injected
Every seam accepts three forms, resolved in this order:
- An instance. Used as is.
- A dotted import string such as
"myapp.notifications.MyBackend". The class is imported and instantiated with no arguments (the backend also acceptsnotification_backend_kwargs). - Nothing. The matching
NOTIFICATION_*setting is read, and the import string found there is resolved as in form 2.
from vintasend.services.notification_service import NotificationService
service = NotificationService(
notification_backend=backend, # an instance
notification_adapters=[DjangoEmailAdapter(renderer, backend)], # instances
attachment_manager="myapp.attachments.S3AttachmentManager", # an import string
# notification_queue_service left out: NOTIFICATION_QUEUE_SERVICE is read
)Adapters given as settings or import strings are pairs of (adapter_import_string, renderer_import_string); either element may itself be a (import_string, kwargs_dict) tuple when the class needs constructor arguments. The service constructs the renderer, then the adapter, and hands the adapter the same backend it uses itself. The configuration page lists every setting.
Sync and AsyncIO services
Almost every piece exists twice. NotificationService is synchronous; AsyncIONotificationService has the same constructor and the same methods as coroutines, and expects the AsyncIO twins of each seam: AsyncIOBaseNotificationBackend, AsyncIOBaseNotificationAdapter, AsyncIOBaseAttachmentManager, AsyncIOBaseNotificationQueueService, AsyncIOBaseNotificationReplicationQueueService and AsyncIOBaseGitCommitShaProvider.
The renderer is the exception and has no async twin. Rendering is in-memory work with nothing to await, so both services call the same synchronous BaseNotificationTemplateRenderer.
from vintasend.services.notification_service import AsyncIONotificationService
service = AsyncIONotificationService(
notification_adapters=[FastAPIMailAdapter(JinjaTemplatedEmailRenderer(), backend)],
notification_backend=backend,
)
await service.create_notification(...)Do not confuse AsyncIOBaseNotificationAdapter with BackgroundNotificationAdapter. The first is async/await. The second is a synchronous adapter that hands delivery to a queue service so a worker delivers later; it has an AsyncIO counterpart too, AsyncIOBackgroundNotificationAdapter.
Everything is passed as an instance to VintaSendFactory.create({...}). There is no settings layer, no import strings and no framework detection.
import { VintaSendFactory } from 'vintasend';
const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
adapters: [emailAdapter],
backend,
logger,
contextGeneratorsMap,
attachmentManager, // optional
queueService, // optional
replicationQueueService, // optional
gitCommitShaProvider, // optional
additionalBackends: [], // optional
options: { raiseErrorOnFailedSend: false },
});A backend that exposes injectAttachmentManager receives the attachment manager at construction time; a backend that does not is left alone. The configuration page lists every key and option.
The NotificationTypeConfig generic
Every module, from the service to each backend, adapter and renderer, is generic over one configuration type:
import type { BaseNotificationTypeConfig } from 'vintasend';
export type NotificationTypeConfig = {
ContextMap: typeof contextGeneratorsMap;
NotificationIdType: number;
UserIdType: number;
};ContextMapis the type of yourcontextGeneratorsMap. It makescontextNamea union of the registered names and typescontextParametersas the parameter of that generator’sgenerate.NotificationIdTypeis the type the backend uses for notification ids (a number for an autoincrement column, a string for a UUID).UserIdTypeis the type ofuserIdin your application.
The factory, the backend factory and the adapter factory all take the same Config so that a notification created through the service is the same type the backend stores and the adapter receives. Define it once, next to the context map, and import it everywhere.
What happens on a send
- The service looks up the adapters for the notification’s type.
- For a background adapter it hands the notification id to the queue service and stops; a worker will finish the job with
delayed_senddelayedSend. - Otherwise it calls the context generator named by the record (see context generators).
- The adapter asks its renderer for the body and delivers it.
- The backend marks the record
SENTorFAILED, and on success stores the context and adapter that were used.
The lifecycle page covers each status, what raises and what is skipped.
Found a mistake? Edit this page on GitHub.