Skip to content
AntFabric Corev1.0.0local

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

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.

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 the event_outbox, so it goes out only if the change commits. ephemeral events (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.

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 the core-notifications workers) 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).

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.

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_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).