Core services
Core services are Nest modules in apps/backend/src. A plugin never imports them; it gets a
scoped version injected through @antfabric/sdk-server, bound to its own plugin id.
| Service | Plugin gets | Scoped how |
|---|---|---|
| Identity | @CurrentUser(), @Permissions(), @Public() |
Only permissions the plugin declares |
| People and presence | PluginPeople |
Read-only directory |
| Files | PluginFiles |
Its own prefix and quota; reads its dependencies’ files |
| Live events | PluginEvents |
Only events it declares |
| Notifications | PluginNotifications |
Only types it declares |
| Workflows | PluginWorkflows |
Only workflows it registers |
| Configuration and secrets | PluginConfig, PluginSecrets |
Only its own keys |
| Audit | PluginAudit |
Actions prefixed with its id |
| Database | PluginDb |
Its own role and schema |
| Contracts | PluginContracts |
Only contracts it declares |
People and presence
Section titled “People and presence”The people directory answers “who is this id”: display name, photo, active or not, by id or by
search. Presence (online, away, offline) comes from the live socket: each app reports active or
idle, and a person is online when any of their apps is. Profile photos are files owned by
core:avatars, shown through a short redirect.
S3-compatible object storage (RustFS locally). Uploads are signed, single-use PUT links for an
exact size and type; the file is pending until the upload is confirmed, and an hourly sweep
removes abandoned ones. Downloads are short-lived links. Bytes never pass through the API. Each
plugin writes under its own prefix with a quota and may read files of the plugins it depends on.
Live events
Section titled “Live events”A Socket.IO gateway on /events, one connection per app, with a Redis adapter across API replicas.
- A plugin declares each event in
plugin.yaml: versioned name, permission to subscribe, JSON schema of the payload. - It publishes with
PluginEvents.publish(event, payload, { users, transaction }): only to the listed people who also hold the permission; in the plugin’s transaction through theevent_outbox, so it goes out only if the change commits.ephemeralevents (typing) skip the outbox. - Apps subscribe with
events.subscribe(name, handler)and reload through the API after a reconnect (events.onResyncRequired). Events carry ids or small payloads, not whole records. - The connection checks the token and the live session; revoking a session closes its sockets.
Notifications
Section titled “Notifications”Telling a person something, even when the app is closed.
- A plugin declares notification types in
plugin.yaml: channels (inbox, push, email), templates per channel, a variables schema, a resolver that fills the variables at delivery time, retries, expiry, and the route a tap opens. - It sends with
PluginNotifications.send({ type, recipients, context, idempotencyKey }). The same key never sends twice. - Core’s delivery workflow (
af.core.notification.deliver.v1, on thecore-notificationsworkers) runs per recipient, channel and device: the person’s switches and preferences, the resolver, the template, then the adapter — SMTP, Expo push, Web Push; the desktop app shows the inbox item as a native notification. - People manage their preferences; administrators configure providers and override templates in
App Admin (
notifications:configure).
Workflows
Section titled “Workflows”Temporal per instance. A plugin declares its workflows, activities and schedules in plugin.yaml;
codegen bundles them for the workers. Starts go through PluginWorkflows.start, which writes to the
workflow_outbox (in the plugin’s transaction when given); a dispatcher starts them, safe across
crashes. Worker pools: plugin-default, core-notifications, plugin-heavy. Each activity gets the
plugin’s own SDK (database role, config, events, notifications) acting for the person who started
the workflow. See Background work.
Configuration and secrets
Section titled “Configuration and secrets”A plugin declares a JSON Schema and defaults (config/); administrators set values in App Admin
(plugins:configure). PluginConfig.get(key) answers 503 while required values are missing, so a
half-configured plugin says so rather than misbehaving. Secrets are declared by name and kept
encrypted in the instance’s secret store (SECRETS_ENCRYPTION_KEY); values are never cached.
Audit and health
Section titled “Audit and health”audit_log is append-only (database triggers refuse updates and deletes). PluginAudit.record
takes the actor and trace id from the request, or the workflow’s initiator in activities; actions
are prefixed with the plugin id. Administrators read it with audit:read.
/health/live (process), /health/ready (database, Redis, every core and plugin migration
applied) and /health (components; a plugin waiting for configuration is degraded, not down).