Skip to content
AntFabric Corev1.0.0local

Repository structure

One Nx monorepo with pnpm workspaces. Apps are deployables, libraries are core’s public surface, plugins are product features, and instance files say which plugins an organisation gets. If you can point at a box on the architecture diagram, you know its folder.

apps/
backend/ # NestJS: API + Temporal workers in one codebase (core services, plugin host)
web/ # React + Vite: the user app (:5173); also the desktop app's screens
admin/ # React + Vite: App Admin (:5174)
desktop/ # Tauri shell around web (src-tauri/, Rust)
mobile/ # Expo (React Native)
app-manager-api/ # NestJS control plane for instances (:3100, own database)
app-manager/ # React + Vite: App Manager (:5175)
documentation/ # Docusaurus: reference docs and plans (:3005)
handbook/ # Astro Starlight: this handbook (:3006)
libs/
sdk-server/ # what plugin server code imports: PluginDb, PluginEvents, decorators, …
sdk-workflow/ # what plugin workflow code imports: pluginActivities, …
sdk-web/ # what screens import: API client, session, live events, people, navigation
app-shell/ # the user and admin app shell: navigation rail, layouts, badges
ui-kit/ # the UI kit: AntFabric UI plus core's extras (web, data, native)
plugin-manifest/ # plugin.yaml and instance file schemas, composition checks
contracts-core/ # types core shares with plugins (AuthUser, event envelope, …)
api-client/ # GENERATED from apps/backend/openapi.json
vendor/antfabric-ui/ # AntFabric UI packages as tarballs, until its registry has a release
plugins/
example/ # the reference plugin; product plugins are cloned here from their own repositories
instances/
local.yaml # the local instance: branding and the plugins it is built with
local.lock.json # its composition lock (versions and manifest digests)
managed/ # instance files the App Manager writes
tools/
scripts/gen-plugins.mts # codegen: reads the instance file, writes the plugin registries
src/generators/plugin/ # pnpm plugin:new

An app is a deployable. It wires libraries and plugins together and owns a process; product rules live in plugins.

App Is Notes
backend NestJS API and Temporal workers One image, three commands: API, workers, migrations
web User app Loads plugin screens from its generated registry
admin App Admin Users, roles, sign-in, notifications, plugin settings, storage, audit
desktop Tauri Wraps the user app’s screens; native notifications, tray, files
mobile Expo Its own screens per plugin (plugins/<name>/mobile)
app-manager-api, app-manager Control plane Companies, instances, releases; one per AntFabric deployment, not per instance
documentation Docusaurus Detailed reference and the build plans
handbook Starlight This site: architecture and developer docs

Libraries are what plugins and apps are allowed to import from core. A plugin imports only @antfabric/* libraries and other plugins’ contracts packages.

Library Used by Holds
@antfabric/sdk-server Plugin server code Scoped services (PluginDb, PluginEvents, PluginNotifications, PluginPeople, PluginFiles, PluginWorkflows, PluginConfig, PluginSecrets, PluginAudit, PluginContracts), decorators, defineActivities, defineNotificationResolver
@antfabric/sdk-workflow Plugin workflow code pluginActivities, deterministic helpers
@antfabric/sdk-web Every screen api, useAuth, events, usePeople, usePresence, useNavigation, definePluginSurface; /client for the phone
@antfabric/ui-kit Every screen Components and tokens; /native for the phone
@antfabric/contracts-core Core and plugins Shared types
@antfabric/plugin-manifest Core and tools Manifest and instance file validation

Each plugin is a self-contained folder with its own package.json, tests and README, and a separate contracts package (@antfabric-contracts/<name>). See plugin anatomy.

Generated From By
*.generated.ts registries in every app instances/local.yaml + plugins/*/plugin.yaml Codegen, before every dev, build and test (git-ignored)
apps/backend/tsconfig.build.generated.json, apps/backend/plugins.generated.json The same Codegen (git-ignored)
instances/local.lock.json The same Codegen (committed)
apps/backend/openapi.json, libs/api-client/src/schema.ts The backend’s controllers and DTOs pnpm api:spec (committed; CI fails when stale)

Never edit generated files; change their source and regenerate.

apps/* → libs/* and plugins (through the generated registries only)
plugins/<name> → libs/* (@antfabric/*) and other plugins' contracts packages
plugins/<name>/contracts → @antfabric/contracts-core only
libs/* → other libs; never apps, never plugins

Core never imports a plugin by name. Nx module-boundary lint rules enforce the rule; a violating import fails CI.

New Goes
A product feature A plugin: pnpm plugin:new <name>
A rule about a plugin’s data That plugin’s service, checked on every call
A table A migration in plugins/<name>/db/migrations (core: apps/backend/src/db/drizzle/migrations)
Something every plugin needs A core service, exposed through @antfabric/sdk-server or sdk-web
A call from one plugin to another A contract in the provider’s contracts package
A live update An event declared in plugin.yaml, published with PluginEvents
Telling someone something A notification type in plugin.yaml, sent with PluginNotifications
Work that outlives a request, or a schedule A Temporal workflow in plugins/<name>/workers
A setting an admin changes config/schema.json in the plugin, read with PluginConfig
A component two plugins need The UI kit
A new API call from a screen Add the route; screens call it through api from sdk-web
Docs apps/handbook (this site) or apps/documentation, in the same merge request