Architecture overview
AntFabric Core is a NestJS modular monolith in an Nx monorepo. Core provides the services every feature needs; every product feature is a plugin compiled into the instances that choose it. Anything that outlives a request runs on Temporal. Each organisation gets its own instance.
Every box links to its page. One instance is one organisation: its own apps, API, workers and infrastructure. Plugins are compiled into the instance that selects them; they never call each other's code or tables, only core's services and each other's contracts.
Key decisions
Section titled “Key decisions”Backend
Section titled “Backend”One NestJS codebase, apps/backend, built into one image with three commands: the API, the
workers (Temporal) and the migration runner. Core services are Nest modules; each plugin’s
server code is a Nest module too, compiled into the same build and mounted at
/api/v1/plugins/<plugin id>. Nothing that must outlive a request lives in a process’s memory:
sessions are rows in Postgres; presence, rate limits and socket fan-out are in Redis; durable work
is in Temporal. So an instance runs as many identical API and worker replicas behind any load
balancer, and any replica can stop at any moment. See Scaling.
Core and plugins
Section titled “Core and plugins”Core never imports a plugin by name. Codegen reads the instance file and writes a registry of the selected plugins; the apps load plugins only through it. A plugin never imports core’s code either: it gets core’s services injected, each scoped to that plugin — its own database role, its own configuration, its own audit actor, its own file prefix. Lint rules and database roles enforce both directions. See Plugins.
One organisation per instance
Section titled “One organisation per instance”An instance is one organisation’s AntFabric: its own database, users, sign-in providers, branding
and plugins. The instance file (instances/<id>.yaml) describes it. There is no tenant column
anywhere, because there are no tenants in a process. See Instances.
Plugins are chosen at build time
Section titled “Plugins are chosen at build time”An instance’s builds contain only the plugins its instance file selects — backend image, user app, App Admin, desktop and phone. Adding a plugin is a change to the instance file, a build and a deploy, not a switch at runtime. What is never shipped cannot be misconfigured or attacked.
One PostgreSQL database per instance. Core owns the public schema; each plugin owns one schema and reaches it as its own database role, which can see nothing else. Changes and the events or workflow starts they cause commit together, through transactional outboxes. Migrations are append-only. See Data.
Access is checked by core per route and by the plugin per record
Section titled “Access is checked by core per route and by the plugin per record”Every route declares the permissions it needs; core checks them before the handler runs. Whether you may see this record depends on the record, so the plugin decides, in its service, on every call — Sales lets you see your own leads and managers see all. Sessions are revocable rows; every request reloads the person’s current roles. See Access and identity.
Live events and notifications are separate
Section titled “Live events and notifications are separate”Live events keep open screens current: one Socket.IO connection per app, permission-checked, addressed to specific people, ids or small payloads. The same events reach other plugins’ server code too, at least once, with retries per subscriber. Notifications tell a person something even when the app is closed: inbox, Expo push, Web Push, native desktop and email, as their preferences allow, never twice for the same key. A plugin uses both through core; neither runs inside a plugin. See Core services.
Async work
Section titled “Async work”Temporal for background jobs, schedules and multi-step work. A plugin declares its workflows and
schedules in its manifest; starts go through an outbox in the caller’s transaction, so a start is
never lost or doubled. Workflows can run child workflows and continue as new for long jobs. Workers
run in pools (plugin-default, core-notifications, and plugin-heavy, started when a plugin has
heavy work). See Background work.
Calls between plugins go through contracts
Section titled “Calls between plugins go through contracts”A plugin that needs another (Sales opening a channel in Chat) asks core’s contract registry for
an implementation of a declared contract. It gets null when an optional provider is not installed,
so it degrades. Core attaches the person the call is for, so a caller cannot act as someone else.
Extension points allow many providers. The provider’s code runs with the provider’s database role,
in the API and in the workers. See
Contracts between plugins.
Clients
Section titled “Clients”Four apps share one client library (sdk-web: API, session, live events, people, navigation) and
one UI kit. The desktop app wraps the user app’s screens; the phone app has its own screens per
plugin and shares their logic. Screens open each other by route id, never by path. See
Clients.
Observability
Section titled “Observability”JSON log lines on stdout with a trace id that is reused or created at the edge. Prometheus metrics
per process, including outbox lag, socket counts and pending deliveries. OpenTelemetry traces
follow one request through the outbox, Temporal and notification delivery. Bodies and query strings
are never logged. /health/live and /health/ready for orchestration; /health lists components.
Transports at a glance
Section titled “Transports at a glance”Full matrix on Transports. The short version:
- Clients speak HTTPS/REST to
/api/v1and Socket.IO to/events, and move file bytes directly to object storage on short-lived signed links. - Inside the API, core services and plugins call each other in process: plugins through scoped SDK services, plugins to plugins through contracts.
- The API and the workers share PostgreSQL (outboxes) and Temporal; workers publish live events and send notifications through the same core services.
- Redis carries presence, rate limits, SSO state, cache invalidation and socket fan-out between replicas.
- Delivery leaves the instance over SMTP, Expo push and Web Push.
Open questions
Section titled “Open questions”- Plugins as packages. Product plugins already live in their own repositories and come into an instance with the devkit (cloned, or added as a packed version). What’s left is published SDK packages and core images, so a plugin builds without a core clone, and automatic releases to the package registry.
- Push to phones. Expo push needs an EAS project id per app; without it the phone gets notifications only in the app.
- Shipping phone and desktop updates. Per-organisation phone builds with over-the-air updates, and a desktop shell that loads the instance’s web app, are the likely shape; not built yet.
- UI slots (one plugin’s component inside another’s screen) are planned with the frontend foundation. See What’s ready and what’s next.
- Navigation layouts (icon rail, sidebar, top bar) chosen per organisation: built; plugin groups and order come next — see Navigation layouts.
- Changing plugins on a running instance through the App Manager is designed and paused.