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.
Layout
Section titled “Layout”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.jsonvendor/antfabric-ui/ # AntFabric UI packages as tarballs, until its registry has a releaseplugins/ example/ # the reference plugin; product plugins are cloned here from their own repositoriesinstances/ 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 writestools/ scripts/gen-plugins.mts # codegen: reads the instance file, writes the plugin registries src/generators/plugin/ # pnpm plugin:newAn 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
Section titled “Libraries”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 |
Plugins
Section titled “Plugins”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 code
Section titled “Generated code”| 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.
The dependency rule
Section titled “The dependency rule”apps/* → libs/* and plugins (through the generated registries only)plugins/<name> → libs/* (@antfabric/*) and other plugins' contracts packagesplugins/<name>/contracts → @antfabric/contracts-core onlylibs/* → other libs; never apps, never pluginsCore never imports a plugin by name. Nx module-boundary lint rules enforce the rule; a violating import fails CI.
Where to put a new thing
Section titled “Where to put a new thing”| 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 |