FAQ
Instances and the App Manager
Section titled “Instances and the App Manager”What is an instance?
Section titled “What is an instance?”One organisation’s own AntFabric: its own database, users, sign-in providers, branding and plugins,
described by one file, instances/<id>.yaml. Organisations never share an instance. See
Instances.
Does each instance have its own App Manager?
Section titled “Does each instance have its own App Manager?”No. The App Manager is the control plane above instances: one App Manager creates, updates, disables and removes many instances. What each instance has is its own App Admin, where that organisation’s administrators manage users, roles, sign-in, notifications and plugin settings.
How do I add a plugin to an organisation?
Section titled “How do I add a plugin to an organisation?”Add it to that instance’s file, rebuild and deploy — the instance’s builds contain only the
plugins its file selects, so adding one is not a switch at runtime. For managed instances the App
Manager writes the file and runs the build; changing plugins on a running instance from the App
Manager is designed but paused. Locally: add the id to instances/local.yaml and run
pnpm --filter backend db:migrate; a running pnpm dev notices the instance file, runs codegen and
restarts the API and the workers.
Which instances run on my machine?
Section titled “Which instances run on my machine?”pnpm dev runs the local instance from source. Instances created through the App Manager run as
Docker containers (af-<company>-<instance>-*) with their own file in instances/managed/, their
own database and their own plugin selection — a plugin built into local is not in them.
Why can’t I remove a disabled instance straight away?
Section titled “Why can’t I remove a disabled instance straight away?”Removal is two stages on purpose: disable (apps stop, data kept), then remove, allowed only
after the grace period (DECOMMISSION_GRACE_DAYS, default 30 days) during which it can be enabled
again. Locally, set DECOMMISSION_GRACE_DAYS=0 in apps/app-manager-api/.env and restart the App
Manager API.
How plugins plug in
Section titled “How plugins plug in”Is core registered into the plugin, or the plugin into core?
Section titled “Is core registered into the plugin, or the plugin into core?”The plugin is plugged into core. Core imports it through the generated registry (never by name
in core’s code), mounts its module at /api/v1/plugins/<id>, and injects core’s services into
it, each scoped to that plugin. The plugin never imports core’s code — only the SDK libraries.
When does a plugin get registered: at build time or at run time?
Section titled “When does a plugin get registered: at build time or at run time?”Both, in three steps — and never while an instance is running:
- Build: codegen reads the instance file, validates manifests and writes the registries with the selected plugins only.
- Deploy: the migration runner creates the plugin’s schema, role and permissions and runs its migrations.
- Start-up: core mounts routes, injects services, registers contracts; workers register workflows and schedules.
See Plugins.
Does an instance’s bundle contain every plugin’s code?
Section titled “Does an instance’s bundle contain every plugin’s code?”No — only the plugins its instance file selects. The backend image compiles only selected plugins’ server code and installs only their dependencies; Vite (web, admin, desktop) and Metro (phone) bundle only what the generated registries import. An instance that selects only Example contains no Chat or Sales code at all.
What may a plugin not do?
Section titled “What may a plugin not do?”Read or write another plugin’s or core’s tables (its database role cannot), import another plugin’s
code (lint), serve a route without a permission or @Public() (core refuses to start), provide
core’s services, or use an event, notification type, workflow or contract it did not declare.
Plugins and core services
Section titled “Plugins and core services”How does a plugin like Chat use core’s services?
Section titled “How does a plugin like Chat use core’s services?”| Chat needs | Core service | How |
|---|---|---|
| Its conversations and messages | PluginDb |
Tables in schema chat, as role af_chat |
| Names, photos, online status | PluginPeople, presence |
get, search, presence; usePeople, usePresence in screens |
| New messages appear without reloading | PluginEvents over core’s socket |
publish('af.chat.message.created.v1', …, { users: members, transaction }) |
| “Someone mentioned you” on the phone | PluginNotifications |
send({ type: 'af.chat.mention', recipients, context, idempotencyKey }) |
| Attachments | PluginFiles |
Signed uploads; downloads through short-lived links |
| Who may create channels, edit window | PluginConfig |
membersCanCreateChannels, editWindowMinutes |
| Archiving channels on record | PluginAudit |
record({ action: 'channel.archived', … }) |
Does a plugin send live updates over its own WebSocket?
Section titled “Does a plugin send live updates over its own WebSocket?”No. Core owns the one socket per app. A plugin declares its events and publishes them through
PluginEvents; core checks permissions, sends only to the listed people and delivers through the
outbox so nothing goes out for a change that did not commit.
So a plugin always notifies people through core’s notification service, which uses the WebSocket?
Section titled “So a plugin always notifies people through core’s notification service, which uses the WebSocket?”Two different services. Live events (over the socket) keep open screens current. Notifications
reach a person even when no app is open — inbox, Expo push, Web Push, desktop and email — through
core’s delivery workflow, honouring their preferences. A plugin often uses both for one action:
Chat publishes message.created to members’ open screens and sends af.chat.mention to the person
mentioned. See Live updates and notifications.
Do we have push notifications?
Section titled “Do we have push notifications?”Yes: Expo push on phones, Web Push in browsers (enabled per browser by the person) and native notifications in the desktop app. Phone push needs an EAS project id and a development build; Expo Go on Android cannot receive remote push.
Plugins working together
Section titled “Plugins working together”What is the contract registry, and why was it added?
Section titled “What is the contract registry, and why was it added?”apps/backend/src/plugins/contract-registry.ts lets one plugin call another’s server code. It was
added with Sales, the first plugin that needed another (Chat): importing Chat’s code is forbidden by
lint, writing Chat’s tables by the database, and calling Chat’s API on the user’s behalf would be
untyped and unscoped. Chat declares and registers contract chat; Sales asks for it and gets
null when Chat is not installed, so it hides “Discuss in Chat”. See
Contracts between plugins.
How is a contract different from an event or a notification?
Section titled “How is a contract different from an event or a notification?”A contract is plugin → plugin, on the server, now (“open a channel”). An event is plugin → open screens (“this lead changed”). A notification is plugin → a person (“your follow-up is due”).
Plugins in their own repositories
Section titled “Plugins in their own repositories”Can a plugin live in its own repository?
Section titled “Can a plugin live in its own repository?”Yes, and product plugins do. Chat is antfabric-v2/plugins/chat and Sales is plugins/sales; core keeps only Example (the UI kit is part of core). Each repository’s root is the plugin, with its own tests and CI. See Plugin repositories.
Is the plugin’s code copied into core?
Section titled “Is the plugin’s code copied into core?”No. Core’s repository never contains a product plugin. A plugin comes into an instance: a
developer’s (pnpm antfabric plugin clone <git-url>) or an organisation’s (pnpm antfabric plugin add <id>@<version> or a packed file). Only that instance’s build contains the plugin, because it
has to run it.
Do I need core’s source to work on a plugin?
Section titled “Do I need core’s source to work on a plugin?”You need a core instance: pnpm antfabric create clones core (main until core has release tags; then --ref <tag>) into a folder of your own,
and you put plugins in its plugins/. You never change core’s files there (pnpm antfabric check
and the pre-commit hook refuse it). Later, published SDK packages and core images replace the
clone; the commands stay the same. Steps: Set up and add plugins.
Why are plugins cloned into plugins/ and not linked?
Section titled “Why are plugins cloned into plugins/ and not linked?”pnpm ignores symlinked workspace folders and Nx hides folders git ignores, so a plugin linked in
from elsewhere is not built. plugin clone puts the repository in plugins/<name> as a real
folder with its own .git; you commit and push from there.
What does the devkit do?
Section titled “What does the devkit do?”The antfabric command is the start of AntFabric as a framework: antfabric create gives you a
core instance of your own (a clone of core’s main, or a tag with --ref), you build plugins in it, antfabric plugin pack turns one into a checked, versioned file, and antfabric plugin add puts that file into
another instance. See Devkit.
Why are plugins packed as source, not compiled?
Section titled “Why are plugins packed as source, not compiled?”Compiled packages are where a public plugin ecosystem ends up, but they change how every app builds plugins, so they come second:
| Piece | What compiled packages require |
|---|---|
| Backend (Nest) | A real tsc build per plugin: faster compilers drop the decorator metadata Nest’s injection needs |
| Workers (Temporal) | A separate workflow build that stays deterministic in Temporal’s sandbox |
| Web, admin, desktop (Vite) | ES modules with React and the SDK left as peers, or two copies of React break hooks |
| Phone (Metro) | Another build for React Native, and Metro resolving plugins from node_modules |
| Codegen | Finding plugins in node_modules and importing each surface’s built entry |
| SDK | Versioned and published first: a compiled plugin is built against one SDK version, so the instance must provide a compatible one |
| Dev loop | A watch build per surface before the app reloads |
Each has pitfalls that show up at run time, not at build time. A source package needs none of
it: the instance compiles the plugin exactly as it compiles its own, and pack type-checks and
lints the plugin first so most errors still surface early. What source gives up: the plugin is
unpacked into plugins/ rather than used from node_modules, and its code is visible, which does
not matter for an open-source framework.
The commands, the metadata file, versioning and the lock stay the same for both. The metadata
carries "format": "source", so a later "format": "compiled" is added behind the same add.
Can a plugin developer change core?
Section titled “Can a plugin developer change core?”No. A plugin lives only in plugins/<name>/. A plugin that needs an edited core cannot be shipped,
because the instance it is added to has the real core. antfabric create records a fingerprint of
every core file in instances/core.json and commits core as cloned. antfabric check reports any
core file that was modified, added or removed. plugin pack refuses to pack, and the git pre-commit
hook refuses to commit, until those files are put back (git checkout -- <file>).
The developer’s own paths are: their plugin folders, instances/, plugins added from a package,
and the files core’s own commands rewrite (pnpm-lock.yaml, the API spec and its client types).
Removing a core plugin with plugin remove --delete is allowed.
It is a guardrail, not a lock: someone can still edit the check itself, which the check reports too. Compiled core packages, where core is not in the instance at all, remove the question entirely. If core needs a change, raise it with the core team.
What is the best way to organise many plugins across web, desktop and phone?
Section titled “What is the best way to organise many plugins across web, desktop and phone?”- One folder per plugin with a
shared/folder for logic and thin screens per platform:web/(also used by desktop),mobile/,admin/. - Each plugin declares its
targets; a web-only plugin simply has nomobile/. - Builds per instance: backend, web and admin per instance; the desktop app as a thin shell that loads the instance’s web app; the phone as per-organisation builds with over-the-air updates for JavaScript changes (native changes need a store release).
- Plugins talk only through contracts, events and navigation by route id.
Layout
Section titled “Layout”Can an organisation choose a top menu or a sidebar instead of the rail?
Section titled “Can an organisation choose a top menu or a sidebar instead of the rail?”Yes. The layout belongs to the shell, not to plugins: the instance file sets the default
(appearance.navigation: rail | sidebar | top), and the organisation’s administrators can change it
in App Admin → Appearance without a rebuild (it changes the user app; App Admin keeps the rail). The
same page sets the order plugins appear in; until then they follow the instance file’s plugins: list. Plugins keep declaring menu entries (optionally with a
group and order) and work in every layout. See Navigation layouts.
Access
Section titled “Access”Which accounts can I use locally?
Section titled “Which accounts can I use locally?”admin@example.com / Admin@123456 (administrator; first sign-in sets up an authenticator app), and
the demo people ada, grace, alan, katherine, linus @demo.test / Demo-Pass-1!
(created by pnpm demo:seed). A superadmin is created once per instance with
pnpm --filter backend instance:first-admin --email … --first-name … --last-name …, which prints a
one-time activation link.
Who sees what in a plugin?
Section titled “Who sees what in a plugin?”Core checks the route’s permissions; the plugin checks the record. In Sales, a salesperson sees
their own leads and the ones where they are in a meeting or own a follow-up; managers
(sales:manage) see all. Someone who may not see a record gets “not found”.
Local development
Section titled “Local development”The app is stuck on “Restoring your session”
Section titled “The app is stuck on “Restoring your session””The screen says why it keeps trying (“Busy”, “No connection”, “The server is not answering”). If the
API is not answering, check curl http://localhost:3000/health/live; if it does not answer, look at
the API lines of pnpm dev and restart it. Type errors no longer stop the API: they show in the
TYPES lines.
A new screen does not show on the phone
Section titled “A new screen does not show on the phone”Metro missed a changed file: pnpm --filter mobile start:clear. If your Wi-Fi address changed,
update EXPO_PUBLIC_API_URL in apps/mobile/.env.
Why did I get signed out in one tab?
Section titled “Why did I get signed out in one tab?”Tabs of the same site share one session: signing out, or signing in as someone else, in one tab signs out the others. To test several people at once, use separate browser profiles or a private window, plus the desktop app and the phone.
Where do I push, and where do merge requests go?
Section titled “Where do I push, and where do merge requests go?”To antfabric/antfabric-v2/core-v1. Older checkouts also have a remote for
client-projects/antfabriccore, a fork whose merge requests default to an upstream boilerplate
project. See Branches and merge requests.