Ecosystem

Dashboard and APIs

The notifications dashboard, the templates management dashboard, and the two HTTP APIs behind them, in both ecosystems.

Showing examples for

Because every notification is a record, it can be listed, previewed, resent and cancelled from outside the application that created it. VintaSend ships that as two pieces separated by one HTTP contract: an API that wraps a configured service, and a dashboard that is a pure client of the API. The same split exists a second time for managed templates.

vintasend-dashboard  ──HTTPS + API key──▶  vintasend-api (Python)   ──▶  vintasend
                                    or ──▶  vintasend-ts-api (TS)   ──▶  vintasend-ts

The API owns everything that needs credentials: the database, template rendering, the GitHub token used for previews. The dashboard owns presentation and user login. It holds no backend, no database credentials and no template renderer, and reads and writes everything over the contract. That is why one dashboard serves both ecosystems, and why a team running Django on one service and Node on another can run a single UI against both.

The notifications API

openapi.yaml is the normative document. It ships byte-identical in vintasend-api (Python) and vintasend-ts-api (TypeScript), so one generated client works against either server. Both expose the same routes: /health, /api/v1/capabilities, /api/v1/notifications with pending, future and one-off listings, one notification by id, its rendered preview, and resend and cancel actions. Every /api/v1 request carries Authorization: Bearer <key>, and errors always use the envelope { "error": { "code", "message", "details"? } }.

The API does not assume what the backend can do. It reads the service’s filter capability report (get_backend_supported_filter_capabilitiesgetBackendSupportedFilterCapabilities) and republishes it at /api/v1/capabilities, so the dashboard greys out a filter the backend cannot evaluate instead of sending it. String lookups and ordering are negotiated the same way: an unsupported ordering is dropped rather than failing the request. One key is kept private: pagination.oneIndexed tells the API whether the backend pages from 1 (Python) or 0 (TypeScript), the API converts, and the wire is unconditionally 1-indexed.

vintasend-api is a Django app plus django-ninja, chosen because the reference backend (vintasend-django) needs a Django app registry to read from. A FastAPI application storing notifications through vintasend-sqlalchemy is served by the same API: the service factory is the only thing it calls.

Mount it in a Django project by installing the app and including its URLs under a prefix:

pip install vintasend-api
# settings.py
INSTALLED_APPS = [
    # ...
    "vintasend_api.dashboard",
]

NOTIFICATION_SERVICE_FACTORY = "myproject.notifications.create_notification_service"
VINTASEND_API_KEY = "..."  # or VINTASEND_API_AUTHENTICATOR
# urls.py
from django.urls import include, path

urlpatterns = [
    path("notifications-api/", include("vintasend_api.dashboard.urls")),
]

That serves /notifications-api/health and /notifications-api/api/v1/. The app has no models and no migrations. Include its URLconf once per project.

The factory is a callable returning a configured service; it is called once per process and reused:

# myproject/notifications.py
from vintasend.services.notification_service import NotificationService


def create_notification_service():
    return NotificationService(
        notification_adapters=[adapter],
        notification_backend=backend,
    )

Run it on its own with the bundled Django project and a WSGI server of your choice:

pip install vintasend-api gunicorn

export DJANGO_SETTINGS_MODULE=vintasend_api.settings
export NOTIFICATION_SERVICE_FACTORY=vintasend_config.create_notification_service
export VINTASEND_API_KEY=...

python -m django check
gunicorn vintasend_api.wsgi:application --bind 0.0.0.0:3333

python -m django check fails on a missing key (vintasend_api.E001) or factory (vintasend_api.E002), so a bad deployment stops before the first request.

Settings and environment variables it reads:

VariableRequiredMeaning
NOTIFICATION_SERVICE_FACTORYyesDotted path to the callable building your service.
VINTASEND_API_KEYunless an authenticator is setShared secret clients send as a bearer token.
VINTASEND_API_AUTHENTICATORnoDotted path to a (request) -> None callable that authenticates callers in place of the key. Raise ApiError.unauthorized(...) or ApiError.forbidden(...) to refuse.
VINTASEND_BACKEND_IDENTIFIERnoRead from a non-primary backend registered in the service.
VINTASEND_UNHANDLED_ERROR_HANDLERnoDotted path to a (exc, request, request_id) callable receiving every unexpected error.
VINTASEND_API_CORS_ORIGINSnoBrowser origins allowed to call the API. Only needed when a browser calls it directly.
GITHUB_REPO, GITHUB_API_KEYpreview onlyRepository holding the templates and a read token, read only when /preview is called.
GITHUB_API_BASE_URL, GITHUB_TEMPLATES_BASE_PATHnoGitHub API root and a prefix added to template paths.
DJANGO_SECRET_KEY, DJANGO_DEBUG, DJANGO_ALLOWED_HOSTS, DJANGO_DB_*noStandard Django knobs for the standalone project.

vintasend-api is a Hono application, so createApp returns something any runtime with a fetch-style handler can serve.

Mount it in your own server:

npm install vintasend-api vintasend
// app/api/v1/[...path]/route.ts — a Next.js app router route handler
import {
  ApiError,
  asNotificationServicePort,
  createApp,
  createGitHubTemplateClientFromEnv,
} from 'vintasend-api';
import { notificationService } from '@/lib/notifications';
import { getSession } from '@/lib/auth';

const app = createApp({
  getService: async () => asNotificationServicePort(notificationService),
  authenticate: async (c) => {
    const user = await getSession(c.req.raw);
    if (!user) throw ApiError.unauthorized('Sign in first.');
    if (!user.canManageNotifications) throw ApiError.forbidden('Not allowed.');
    return {};
  },
  getTemplateClient: () => createGitHubTemplateClientFromEnv(),
  onUnhandledError: (error, _c, { requestId }) => errorTracker.capture(error, { requestId }),
});

const handler = (request: Request) => app.fetch(request);
export { handler as GET, handler as POST };

getService returns the service your application already sends with, wrapped by asNotificationServicePort. authenticate runs before every /api/v1 route and replaces the shared key; throw ApiError.unauthorized or ApiError.forbidden to refuse. Behind Express, serve app.fetch through getRequestListener from @hono/node-server on a server.all(...) route.

Run it on its own with the vintasend-api command, which needs @hono/node-server installed and a module that default-exports a factory returning a configured service:

VINTASEND_API_KEY=... VINTASEND_SERVICE_MODULE=./vintasend.config.js npx vintasend-api

Environment variables it reads:

VariableRequiredMeaning
VINTASEND_API_KEYyesShared secret clients send as a bearer token.
VINTASEND_SERVICE_MODULEnoModule that builds the service. Default ./dist/vintasend.config.js.
VINTASEND_BACKEND_IDENTIFIERnoRead from a non-primary backend registered in the service.
VINTASEND_API_CORS_ORIGINSnoComma-separated browser origins allowed to call the API.
PORT, HOSTnoListen address. Defaults 3333 and 0.0.0.0.
GITHUB_REPO, GITHUB_API_KEYpreview onlyRepository holding the templates and a read token, read only for /preview.
GITHUB_API_BASE_URL, GITHUB_TEMPLATES_BASE_PATHnoGitHub API root and a prefix added to template paths.

The notifications dashboard

vintasend-dashboard is a Next.js application for browsing, filtering, previewing, resending and cancelling notifications, with Clerk or Auth0 login selected by environment variable. It is the same application whichever API is behind it.

The API key is a server-side secret, so the browser never calls the API directly. The client points at /api/vintasend, a route inside the dashboard that checks the visitor’s session and re-signs the call with VINTASEND_API_KEY. That route is the only place the key exists.

npm install
cp .env.example .env.local
npm run dev        # http://localhost:3000
VariableMeaning
VINTASEND_API_URLBase URL of the API, for example http://localhost:3333.
VINTASEND_API_KEYThe key the API was started with. Server-side only.
AUTH_PROVIDERclerk or auth0.
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEYClerk credentials.
AUTH0_SECRET, APP_BASE_URL, AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRETAuth0 v4 credentials; auth routes mount at /auth/*.

Everything that is not UI lives in vintasend-dashboard-core: the typed client generated from openapi.yaml, TanStack Query hooks over it, and notification filters that live in the URL so a filtered view survives a reload. The dashboard repository is meant to be read as an example. To build the same screens inside your own admin app with your own design system, install the core and keep the proxy route:

npm install vintasend-dashboard-core @tanstack/react-query
import { useFilteredNotifications } from 'vintasend-dashboard-core';
import { useNextRouterAdapter } from 'vintasend-dashboard-core/next';

const { notifications, filters, setFilters, page, setPage, setSort, hasNextPage } =
  useFilteredNotifications({ router: useNextRouterAdapter() });

createVintaSendClient({ baseUrl: '/api/vintasend' }) points the hooks at your proxy; getHeaders or apiKey are for a server-side client or an API fronted by your own session.

The templates management API

The templates side repeats the split for managed templates. vintasend-templates-management-api (Python) and vintasend-ts-templates-management-api (TypeScript) expose a configured ManagedTemplateService over HTTP with the same conventions as the notifications API: bearer-token auth, the { data } / { error } envelope, 1-indexed pages, camelCase on the wire, and a byte-identical openapi.yaml.

The routes cover template versions (GET/POST /api/v1/templates, /templates/{key}/versions), the lifecycle (activate, deactivate, archive, status, status-history), composition (what the engine actually receives, inheritance resolved), preview against a context you supply, and /api/v1/tags. Two conventions to know: GET /templates lists one row per key by default (mostRecentActiveVersion=true), and only a never-published version can be deleted; a published one answers 409 CONFLICT.

Capabilities are negotiated here too, with a twist. The fields.*, stringLookups.* and logical.* namespaces default to supported and an unsupported filter is dropped, while orderBy.* defaults to not supported and an unsupported ordering is a 400. A UI reads /api/v1/capabilities and only makes a column sortable when the backend has declared it.

pip install vintasend-templates-management-api
# settings.py
INSTALLED_APPS = [
    # ...
    "vintasend_templates_management_api.templates_manager.apps.TemplatesManagerConfig",
]

MANAGED_TEMPLATE_SERVICE_FACTORY = "myproject.templates.create_managed_template_service"
VINTASEND_API_KEY = "..."  # or VINTASEND_API_AUTHENTICATOR
# urls.py
urlpatterns = [
    path("templates-api/", include("vintasend_templates_management_api.templates_manager.urls")),
]

The URL namespace is vintasend_templates_management_api, so a project can mount it beside vintasend-api without collision, and VINTASEND_API_AUTHENTICATOR has the same name and shape in both packages so one function can guard both.

Standalone:

pip install vintasend-templates-management-api gunicorn
export DJANGO_SETTINGS_MODULE=vintasend_templates_management_api.settings
django-admin check
gunicorn vintasend_templates_management_api.wsgi:application --bind 0.0.0.0:3334
VariableRequiredMeaning
MANAGED_TEMPLATE_SERVICE_FACTORYyesDotted path to the callable building your ManagedTemplateService.
VINTASEND_API_KEYunless an authenticator is setShared secret clients send as a bearer token.
VINTASEND_API_AUTHENTICATORno(request) -> None, replacing the shared-key check.
MANAGED_TEMPLATE_BACKEND_NAMEnoBackend name every new template is stored under, overriding the create body.
MANAGED_TEMPLATE_ACTOR_RESOLVERno(request) -> str | None, recorded as changedBy on status changes in place of the body.
MANAGED_TEMPLATE_UNHANDLED_ERROR_HANDLERno(exc, request, request_id) -> None for unexpected errors.
VINTASEND_API_CORS_ORIGINSnoBrowser origins allowed to call the API.
npm install vintasend-templates-management-api vintasend vintasend-managed-templates
// app/api/v1/[...path]/route.ts
import { ApiError, createApp } from 'vintasend-templates-management-api';

const app = createApp({
  authenticate: async (c) => {
    const user = await mySession(c);
    if (!user) throw ApiError.unauthorized('Sign in to manage templates.');
    if (!user.canEditTemplates) throw ApiError.forbidden('You cannot manage templates.');
    return { actor: user.email }; // recorded as changedBy on every status change
  },
  getService: async () => myConfiguredService,
  templateManagedBackend: 'medplum',
  corsOrigins: ['https://admin.example'],
  onUnhandledError: (error, c, { requestId }) => errorTracker.capture(error, { requestId }),
});

const handler = (request: Request) => app.fetch(request);
export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE };

templateManagedBackend stores every new template under that backend name whatever the create body says. Standalone, with @hono/node-server installed:

MANAGED_TEMPLATE_API_KEY=... MANAGED_TEMPLATE_SERVICE_MODULE=./templates.config.js \
  npx vintasend-templates-management-api
VariableRequiredMeaning
MANAGED_TEMPLATE_API_KEYyesShared secret clients send as a bearer token.
MANAGED_TEMPLATE_SERVICE_MODULEnoModule default-exporting a function that returns the ManagedTemplateService. Default ./dist/vintasend-templates.config.js.
MANAGED_TEMPLATE_API_CORS_ORIGINSnoComma-separated browser origins. Leave empty for server-side clients only.
PORT, HOSTnoDefaults 3334 and 0.0.0.0.

The templates management dashboard

vintasend-templates-management-dashboard is the write-side sibling of the notifications dashboard: create templates, create versions (there is no edit; a new version is the edit, and omitted fields carry forward), move versions through the lifecycle using only the transitions each version reports in allowedTransitions, preview against a typed context, and manage tags. The detail panel splits Source (what someone typed) from Composition (the flat string the engine receives).

It follows the same proxy pattern, at /api/templates, and the same Clerk or Auth0 login:

npm install
cp .env.example .env.local
npm run dev
VariableMeaning
TEMPLATES_API_URLBase URL of the templates API, for example http://localhost:3334.
TEMPLATES_API_KEYThe key the API was started with. Server-side only.
AUTH_PROVIDER and the Clerk or Auth0 variablesSame as the notifications dashboard.

Its data layer is vintasend-templates-management-dashboard-core, installed with npm install vintasend-templates-management-dashboard-core @tanstack/react-query. createTemplatesClient({ baseUrl: '/api/templates' }) and TemplatesProvider set it up, and useFilteredTemplates exposes sortableFields and canSortBy so a header only becomes clickable once the backend has declared the field.

Found a mistake? Edit this page on GitHub.