Skip to content
AntFabric Corev1.0.0local

FAQ

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.

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.

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.

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:

  1. Build: codegen reads the instance file, validates manifests and writes the registries with the selected plugins only.
  2. Deploy: the migration runner creates the plugin’s schema, role and permissions and runs its migrations.
  3. 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.

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.

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.

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.

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

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.

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.

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.

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 no mobile/.
  • 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.

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.

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.

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”.

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.

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.

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.