Plugin System Guide

This guide explains how to extend Business M by creating and integrating new domain plugins.

1. Backend Plugin Structure

A backend plugin is a standard Framework M App defined as a library.

Folder Structure

libs/my_plugin/
├── src/
│   └── my_plugin/
│       ├── __init__.py      # App definition
│       ├── doctypes/        # Domain entities
│       ├── services/        # Business logic
│       └── bootstrap.py     # DI wiring & extensions
├── pyproject.toml
└── README.md

Entry Point

In pyproject.toml, register the app and optional bootstrap/container:

[project.entry-points."framework_m.apps"]
my_plugin = "my_plugin:app"

[project.entry-points."framework_m.bootstrap"]
my_plugin_init = "my_plugin.bootstrap:MyPluginBootstrap"

2. Extending Core DocTypes

Use the Bounded Context pattern. Instead of adding fields directly to core Item, create a MyPluginItem in your library:

class MyPluginItem(BaseDocType):
    item: str = Field(description="Link to core Item")
    special_field: str = Field(...)

    class Meta:
        table_name = "my_plugin_item"

3. Frontend Plugin Structure

Frontend plugins are integrated into the Desk UI at build-time.

Folder Structure

libs/my_plugin/frontend/
├── src/
│   ├── pages/
│   ├── components/
│   └── plugin.config.ts    # Plugin Manifest
├── package.json
└── vite.config.ts

Manifest (plugin.config.ts)

The manifest defines how your plugin integrates into the UI:

import type { FrameworkMPlugin } from "@framework-m/plugin-sdk";

const plugin: FrameworkMPlugin = {
  name: "my_plugin",
  version: "0.1.0",

  manifests: [
    {
      app_id: "my_plugin",
      label: "My Plugin",
      icon: "box",
      resources: [
        {
          name: "my_plugin.dashboard",
          label: "Dashboard",
          route: "/my-plugin/dashboard",
        }
      ]
    }
  ],

  routes: [
    {
      path: "/my-plugin/dashboard",
      element: () => import("./pages/Dashboard"),
    }
  ]
};

export default plugin;

4. Integration into Business M

To enable your plugin in the main application:

Backend Integration

Add the library to apps/business-m/pyproject.toml or install it in the environment.

cd apps/business-m
uv add --path ../../libs/my_plugin

Frontend Integration

Add the plugin path to apps/business-m/frontend/plugin.config.ts (or the discovery configuration). Ensure the library is linked via pnpm:

cd apps/business-m/frontend
pnpm add ../../../libs/my_plugin/frontend

5. Development Tips

• Namespacing: Always prefix your DocTypes and menu items to avoid collisions (e.g., my_plugin.settings).
• Isolation: Use m_protocols to communicate with other libraries. Avoid direct imports of other domain logic.
• Seeding: Use m seed to populate initial data required by your plugin.