🔌 Plugin Development Guide

Interface Definition

The interface is deliberately slim. All identity and metadata lives on the Manifest record rather than as separate interface properties, and the optional hooks live on separate interfaces rather than as default implementations here — so a plugin's class declaration tells you what it does before you read a line of its body.

// ============================================================================
// REQUIRED — every plugin implements this, and this is all of it
// ============================================================================
public interface IPlugin
{
    // All identity + metadata (id, name, version, icon, capabilities, ...).
    // This is the single place an author describes the plugin.
    PluginManifest Manifest { get; }

    // Convenience shortcut for Manifest.Id (the host keys/routes plugins by this).
    string Id => Manifest.Id;

    // Convenience shortcut for Manifest.Slug — the id's last dot-segment, lower-cased
    // (the host keys /plugin/{slug} URLs, the launcher, nav and gating by this).
    string Slug => Manifest.Slug;

    // Register the plugin's services into DI. Runs in every plugin-aware host —
    // Web, InternalApi and BackgroundWorker. Repositories, application services, settings
    // binding, and DI-resolved contribution providers (IPluginSectionNavProvider,
    // IChromeProvider, IPublicRouteAllowList) go here.
    // Example: services.AddScoped<IMyService, MyService>();
    Task RegisterServicesAsync(IServiceCollection services, IConfiguration configuration);
}

// ============================================================================
// OPT-IN — implement one alongside IPlugin only if your plugin does that thing.
// The host probes with `is IPluginXxx` and skips a plugin that does not.
// ============================================================================

// The plugin's own pages and widgets.
public interface IPluginUiContributor
{
    // Pages in the org-admin area, under /admin/plugin/{slug}/… (admin nav Plugins group).
    IEnumerable<PluginAdminPage> GetAdminPages() => [];

    // Pages in the platform-admin area, under /platform/plugin/{slug}/….
    IEnumerable<PluginAdminPage> GetPlatformPages() => [];

    // Components rendered into MainLayout slots: Header (sticky-friendly, top of the
    // page-content scroll), Footer (below the page body), or Floating (outside the
    // layout — for position:fixed overlays like a floating action button).
    IEnumerable<LayoutComponentRegistration> GetLayoutComponents(IServiceProvider? services = null) => [];

    // Route metadata for gating + launcher tile role resolution. Actual page routing
    // is driven by each component's @page directive — this is declaration only.
    IEnumerable<PluginRoute> GetRoutes() => [];
}

// Data the plugin needs seeded before it can be used. Both are idempotent: the
// platform seed runs at every boot, and the per-org setup runs on install too.
public interface IPluginProvisioner
{
    // Seed the plugin's PLATFORM-WIDE defaults (e.g. its single platform ApiModel).
    Task SeedPlatformDefaultsAsync(IServiceProvider services, CancellationToken cancellationToken = default)
        => Task.CompletedTask;

    // Set the plugin up FOR ONE organisation — per-org seed data, role definitions,
    // its settings document. Runs when a new org is provisioned AND when an admin
    // installs the plugin into an existing org (hence "for", not "new").
    Task<bool> SetupForOrganisationAsync(Organisation organisation, string? adminUserId = null, IServiceProvider? services = null)
        => Task.FromResult(true);
}

// Recurring sweeps. Called in the host that runs them — the BackgroundWorker under
// Full, the Web host under Lite — so AddHostedService here cannot double-fire.
public interface IPluginBackgroundServices
{
    Task RegisterBackgroundServicesAsync(IServiceCollection services, IConfiguration configuration);
}

// Once-per-process work after the host starts. Rare, and it must be CHEAP —
// anything per-tenant belongs in SetupForOrganisationAsync or a sweep.
public interface IPluginStartup
{
    Task OnStartupAsync(IServiceProvider services, CancellationToken cancellationToken = default);
}

// Web request pipeline — middleware, SignalR hubs, endpoints. Web host only, and it
// lives in BlazorBlueprint.Web.Shared because it takes WebApplication.
// Example: app.MapHub<MyHub>("/hubs/plugin/myplugin");
//
// Your hub class MUST declare which tenant its connections act for, or the host
// refuses it at connect:
//
//   [HubOrganisationScoped]                        // one org, members only
//   [HubOrganisationScoped(AllowAnonymous = true)] // one org, public widget
//   [HubPlatformScoped]                            // deployment-wide, no tenant
//
// The host then resolves the organisation once, verifies membership, and sets the
// tenant on every invocation — so IRepository<T> works inside a hub method.
// Never take an organisationId as a hub method parameter; a client can forge it.
// Read HubConnectionTenant.OrganisationId(Context) when you need the id itself.
public interface IWebPluginConfigurator
{
    Task ConfigureWebAppAsync(WebApplication app);
}

Why separate interfaces rather than one interface of optional methods. Nine optional hooks had accumulated on IPlugin as default implementations, one at a time, each individually harmless — which is exactly why nothing stopped them. A default is free to add and free to ignore, and those are not the same thing: a plugin's class declaration stopped saying what the plugin did, and every author ended up writing stubs to say "nothing here". Ten of the eleven implementations of the startup hook were an empty Task.CompletedTask, most with a comment explaining the emptiness — and nothing told them apart from the one that was real. The type header answers it now.

Note that the members within IPluginUiContributor and IPluginProvisioner still have defaults, and that is the line being drawn: those are facets of one concern — admin pages but no platform pages is normal — rather than separate concerns. Four honest interfaces beat six one-member ones.

A plugin that implements none of them is a complete plugin, not a degraded one: it still gets its launcher tile (the dashboard route is generated from the slug), it is still installable per organisation, and every host aggregation simply skips it.

Settings classes declare themselves. A class the plugin stores under its own key in the OrganisationPlugins / PlatformPluginInstall dictionaries is marked with [PluginSettings], and the active backend registers whatever it needs — so the plugin still carries no database-driver reference:

[PluginSettings]
public sealed class MyPluginSettings
{
    public string SomeOption { get; set; } = "";
}

It replaced a GetPolymorphicSettingsTypes() list, and the reason is worth knowing because it generalises: a list kept in a different file from the types it names can drift in exactly one direction, and does it silently. Add a second settings class, forget to add it to the list, and on MongoDB it falls back to a BsonDocument at read time — nothing fails at build, nothing fails at boot, and what you see is settings appearing to revert on save. Declared on the type, there is only one place to write it.

All identity / presentation / declared-capability fields live on the PluginManifest record. Because it's a record with sensible defaults, new fields can be added over time without breaking any existing plugin:

public sealed record PluginManifest
{
    public required string Id { get; init; }    // "BlazorBlueprint.Plugins.MyPlugin" — keyed/routed by the last dot-segment
    public required string Name { get; init; }  // display name shown on tiles, nav, plugin management

    public string Version { get; init; } = "1.0.0";
    public string Description { get; init; } = "";
    public string Author { get; init; } = "";
    public string Category { get; init; } = "General";    // grouping label, e.g. "Marketing"

    // FluentUI icon name (e.g. "Briefcase", "Star") for the launcher tile / nav heading.
    // Unknown/blank falls back to a generic puzzle-piece glyph.
    public string Icon { get; init; } = "PuzzlePiece";

    public bool IsPremium { get; init; }                   // gated behind a subscription plan when billing is on
    public PluginScope Scope { get; init; } = PluginScope.Tenant;   // all orgs vs. platform org only

    // Host capabilities this plugin uses — an HONEST DECLARATION for operator review,
    // NOT an enforced sandbox (plugins are full-trust in-process code). List exactly
    // what the plugin touches.
    public IReadOnlyList<PluginCapability> Capabilities { get; init; } = [];

    // Ids of other plugins this one needs loaded + enabled.
    public IReadOnlyList<string> Dependencies { get; init; } = [];
}

public enum PluginCapability
{
    TenantData,         // reads/writes the current org's data via IRepository<T>
    PlatformData,       // reads the platform DB / other tenants via IPlatformRepository<T> — review carefully
    BackgroundJobs,     // registers recurring IHostedService jobs in the worker
    Payments,           // takes payments through the host IPaymentService
    Sms,                // sends SMS through the host ISmsService
    InboundEmail,       // receives inbound email (e.g. a Mailgun inbound-route handler)
    OutboundWebhooks,   // delivers outbound webhooks to third parties
    Ai,                 // calls AI models through the host IApiRequestDispatcher pipeline
    FileStorage,        // stores/serves files through the host IFileStorage
    PublicRoutes,       // serves anonymous public routes (declared via IPublicRouteAllowList)
    ChromeSuppression,  // can suppress the platform header/nav (via IChromeProvider)
}

Four rules

1. Services run everywhere. RegisterServicesAsync is called by every plugin-aware host — Web, InternalApi and BackgroundWorker — on both topologies. Anything a plugin needs in more than one process is registered there.

2. Sweeps run in exactly one process, and it is not always the worker. IPluginBackgroundServices.RegisterBackgroundServicesAsync is called by the BackgroundWorker under Full, and by the Web host under Lite, where there is no worker container — the switch is BackgroundServices:RunInProcess. Registering hosted services anywhere else is how a sweep fires twice.

3. REST controllers run in exactly one process too, on a different switch. The InternalApi serves them under Full — that host exists to take work off the front end and sit behind the firewall — and the Web host serves them under Lite. The switch is Services:InternalApi:Enabled. It is deliberately NOT the same key as rule 2: "where do sweeps run" and "which host serves HTTP" are separate questions, and a deployment may one day want them apart.

4. A plugin must never branch on the topology itself. No if (lite), no injecting IConnectionMultiplexer (Lite has no Redis), no assuming the InternalApi is reachable. Write the plugin once and let the host decide; where a plugin genuinely needs the answer — a typed client's base address, say — read it through PluginApiHosting rather than inventing a second reader of the flag.

Step 1: Create Plugin Project

# Create new Razor Class Library project
dotnet new razorclasslib -n BlazorBlueprint.Plugins.MyPlugin
cd BlazorBlueprint.Plugins.MyPlugin

# Add project references
dotnet add reference ..\..\Core\BlazorBlueprint.Application\BlazorBlueprint.Application.csproj
dotnet add reference ..\..\Core\BlazorBlueprint.Domain\BlazorBlueprint.Domain.csproj

# Only if your pages use the shared UI components (console styles, toasts, breadcrumbs)
dotnet add reference ..\..\Web\BlazorBlueprint.Web.Shared\BlazorBlueprint.Web.Shared.csproj

Step 1b: Declare the assembly as a plugin

One line in the plugin's .csproj. The id it carries is what prefixes the plugin's tables and collections, so it is persisted state — pick it once and do not change it later, because renaming it renames nothing that already exists and the plugin simply starts reading empty tables.

<ItemGroup>
  <AssemblyAttribute Include="BlazorBlueprint.Domain.Attributes.PluginAssemblyAttribute">
    <_Parameter1>myplugin</_Parameter1>
  </AssemblyAttribute>
</ItemGroup>

There is no naming convention: an assembly is a plugin only if it carries this attribute. Nothing is inferred from what it is called, so name your assembly whatever suits you.

The id must equal the last dot-segment of your PluginManifest.Id, lower-cased — a manifest id of Acme.Plugins.Billing means billing. The host checks that at boot and refuses to start if the two disagree, because they are compared against each other on a real path: this id prefixes the plugin's tables and collections, the manifest slug is what routes and gates it, and the tenant schema gate matches one against the other. A mismatch makes that gate silently stop firing for your plugin.

Step 2: Implement the Plugin Class

Implement IPlugin, then add whichever opt-in interfaces your plugin actually needs. The one below has pages, so it takes IPluginUiContributor; it has no seed data, no sweeps and no pipeline wiring, so it says nothing about those.

// Import necessary namespaces
using BlazorBlueprint.Application.Interfaces;     // IPlugin, PluginManifest, PluginCapability
using BlazorBlueprint.Domain.Constants;          // ApplicationRoleConstants for authorization
using Microsoft.Extensions.DependencyInjection;    // IServiceCollection for DI
using Microsoft.Extensions.Configuration;        // IConfiguration for settings

namespace BlazorBlueprint.Plugins.MyPlugin;

/// <summary>
/// Main plugin class. IPlugin is required; IPluginUiContributor is here because this
/// plugin has pages of its own. Read the type header as the table of contents.
/// </summary>
public class MyPlugin : IPlugin, IPluginUiContributor
{
    // ========================================================================
    // MANIFEST (REQUIRED) - all identity + metadata lives here
    // ========================================================================

    /// <summary>
    /// Everything the plugin says about itself: id, display name, version, icon,
    /// and the host capabilities it touches (declared for operator review).
    /// </summary>
    public PluginManifest Manifest { get; } = new()
    {
        // Unique id. Convention: "BlazorBlueprint.Plugins.{PluginName}".
        // The host keys/gates/routes the plugin by the LAST dot-segment
        // ("myplugin" here → /plugin/myplugin). Keep it unique.
        Id = "BlazorBlueprint.Plugins.MyPlugin",

        // Display name shown on launcher tiles, nav, and plugin management.
        Name = "My Plugin",

        Version = "1.0.0",
        Description = "A sample plugin that demonstrates basic functionality",
        Author = "Your Name",
        Category = "Utility",                  // grouping label in the UI

        // FluentUI icon name for the launcher tile / section-nav heading.
        // Unknown/blank falls back to a generic puzzle-piece glyph.
        Icon = "Settings",

        IsPremium = false,                     // true = gated behind a subscription plan when billing is on

        // Honest declaration of what this plugin touches, for operator review
        // (NOT an enforced sandbox). List exactly what you actually use.
        Capabilities = [PluginCapability.TenantData],
    };

    // ========================================================================
    // REGISTER SERVICES (REQUIRED METHOD)
    // ========================================================================

    /// <summary>
    /// Registers services your plugin needs in dependency injection.
    /// Runs in EVERY host (Web, InternalApi, BackgroundWorker).
    /// Services registered here can be injected into your pages and components.
    /// </summary>
    public async Task RegisterServicesAsync(IServiceCollection services, IConfiguration configuration)
    {
        // Register your plugin's services here.
        // AddScoped means a new instance is created for each HTTP request.
        // Other options: AddSingleton (one instance for entire app), AddTransient (new instance every time)
        services.AddScoped<IMyService, MyService>();

        // Cross-cutting host contributions are registered as DI providers here too,
        // so the host discovers them without referencing your plugin. The in-plugin
        // section nav (the sidebar on /plugin/myplugin/*) is one — see below.
        services.AddSingleton<IPluginSectionNavProvider, MyPluginSectionNavProvider>();

        // You can also register:
        // - Background services: add IPluginBackgroundServices to the class declaration
        // - Options/configuration: services.Configure<MyOptions>(options => { ... });
        // - Repositories, other services, etc.

        await Task.CompletedTask; // Required for async method
    }

    // ========================================================================
    // AUTHORIZING YOUR PAGES — use the host's attributes, not a hand-written role list
    // ========================================================================
    //
    //   @attribute [AuthorizePluginAdmin(MyPluginRoles.Admin)]              admin page
    //   @attribute [AuthorizePluginUser(MyPluginRoles.Admin, ApplicationRoleConstants.MEMBER)]
    //   @attribute [AuthorizePlatformAdmin]                                 /platform/plugin/* page
    //   @attribute [AuthorizeOrganisationMember]                            any active member
    //   PluginRoles.IsModerator(user, MyPluginRoles.Admin)                   a check in code
    //
    // Declare ONE role of your own (MyPluginRoles.Admin) and compose nothing. The two
    // administrator tiers — ORGANISATIONADMIN and PLATFORMADMIN — are added by the host.
    //
    // Why this matters: PluginOrganisationSetupBase grants your admin role to whoever
    // INSTALLED the plugin and to nobody else. An organisation admin added later holds
    // none of it, and a platform admin inside an organisation they are not a member of
    // holds neither it nor ORGANISATIONADMIN. So a page written as
    // [Authorize(Roles = MYPLUGINADMIN)] compiles, boots, runs — and refuses the two
    // administrators who are most likely to open it, with nothing anywhere reporting a
    // fault. The symptom is a card in the settings hub over a page that refuses the
    // person who clicked it.
    //
    // [Authorize(Roles = ...)] needs a compile-time constant, which is why the rule cannot
    // be a shared method call at the call site. These attributes do the composition in
    // their constructors instead, so your page still passes a const.

    // ========================================================================
    // ROUTES (OPTIONAL METHOD) - metadata for gating + tile role resolution
    // ========================================================================

    /// <summary>
    /// Declares the routes (pages) your plugin provides. This is METADATA only
    /// (gating + launcher tile role resolution) — actual page routing is driven by
    /// each component's @page directive. From IPluginUiContributor.
    /// </summary>
    public IEnumerable<PluginRoute> GetRoutes()
    {
        // 1. Main plugin landing page (the "app dashboard")
        // This is where users go when they click the plugin tile in /apps.
        // Plugin's main entry — renders under MainLayout with the host's
        // PluginSectionNav sidebar (replaces the platform NavMenu while inside the
        // plugin). Settings + admin-only pages live under /admin/plugin/{pluginname}/*.
        yield return new PluginRoute
        {
            Route = "/plugin/myplugin",                             // Canonical dashboard URL
            ComponentType = typeof(Web.Pages.Admin.Index),        // The Razor component to render
            RequiresAuthentication = true,                        // Must be logged in

            // Who should SEE the launcher tile — NOT who may open the page (that is the
            // @attribute on the component). DeterminePluginRequiredRole unions the
            // RequiredRole of every route and admin page, so naming only an admin tier here
            // makes the tile invisible to ordinary members of every organisation.
            // UserRolesFor adds the two administrator tiers for you; never write the bare
            // role name, or the two administrators who do not hold it are excluded.
            RequiredRole = PluginRoles.UserRolesFor(
                MyPluginRoles.Admin, ApplicationRoleConstants.MEMBER)
        };

        // 2. Public route - accessible to everyone
        // Route: /plugin/myplugin/mypage
        yield return new PluginRoute
        {
            Path = "/plugin/myplugin/mypage",
            ComponentType = typeof(Web.Pages.MyPage),
            RequiresAuthentication = false
        };

        // 3. Admin route - settings page
        // Only ORGANISATIONADMIN users can access this.
        // Route: /admin/plugin/myplugin/settings — renders under AdminLayout
        // because it has a "deeper" path segment after the plugin name.
        yield return new PluginRoute
        {
            Path = "/admin/plugin/myplugin/settings",
            ComponentType = typeof(Web.Pages.Admin.Settings),
            RequiresAuthentication = true,
            RequiredRole = ApplicationRoleConstants.ORGANISATIONADMIN
        };
    }

    // ========================================================================
    // ADMIN PAGES (OPTIONAL METHOD)
    // ========================================================================

    /// <summary>
    /// Defines admin pages that appear in the admin nav's Plugins group. From
    /// IPluginUiContributor — drop the interface entirely if you have none.
    /// </summary>
    public IEnumerable<PluginAdminPage> GetAdminPages()
    {
        // These admin pages appear in the admin nav's Plugins group, and the host also
        // builds a settings hub at the bare /admin/plugin/myplugin from this same list.
        // Only list genuinely admin / configuration pages here — user-facing dashboard
        // pages live at /plugin/myplugin/* and are reached via the host PluginSectionNav.
        yield return new PluginAdminPage
        {
            Title = "Settings",                            // Display name
            Route = "/admin/plugin/myplugin/settings",     // Write the real route out
            Icon = "Settings",                             // FluentUI icon name
            RequiredRole = ApplicationRoleConstants.ORGANISATIONADMIN,
            Order = 100                                    // Lower = appears first
        };
    }
}

Section navigation (the sidebar on /plugin/{name}/*)

The left sidebar shown while a user is inside your plugin is contributed through a DI extension point — IPluginSectionNavProvider — not a method on IPlugin. You register one provider per plugin in RegisterServicesAsync (see the registration line above); the host discovers it by slug and renders it in place of the platform NavMenu, with no per-plugin knowledge of its own.

using BlazorBlueprint.Application.Interfaces;

namespace BlazorBlueprint.Plugins.MyPlugin;

/// <summary>
/// Supplies the rows for this plugin's in-plugin section nav. The host can't
/// reference the plugin assembly, so it discovers this provider via DI and matches
/// it by PluginSlug. This nav is static (no tenant data), so a cached list is fine;
/// a per-org nav can query inside GetItemsAsync instead.
/// </summary>
public sealed class MyPluginSectionNavProvider : IPluginSectionNavProvider
{
    private static readonly IReadOnlyList<PluginSectionNavItem> Items = new List<PluginSectionNavItem>
    {
        // PluginSectionNavItem(Label, Href, Icon, MatchAll = false, RequiredRole = null, Section = null)
        // Icons are FluentUI Size20 names. MatchAll = exact-match highlighting (use it
        // on the dashboard row so it isn't lit on every nested route).
        new("Dashboard", "/plugin/myplugin", "Home", MatchAll: true),
        new("My page",   "/plugin/myplugin/mypage", "DocumentText"),
    };

    // Plugin slug as it appears in /plugin/{slug}/* (lower-case).
    public string PluginSlug => "myplugin";

    // Heading shown above the section nav (null = host falls back to the slug).
    public string? Title => "My Plugin";

    // Runs when the sidebar renders for the matching slug — keep it cheap.
    public Task<IReadOnlyList<PluginSectionNavItem>> GetItemsAsync(CancellationToken cancellationToken = default)
        => Task.FromResult(Items);
}

Step 3: Add to Solution

A plugin lives at Plugins/{Name}/{AssemblyName}/ — the same shape as the drop-in layout at run time, so there is one path to remember rather than two:

# Add plugin to solution — the path Plugins.props will reference in the next step
dotnet sln add Plugins/MyPlugin/BlazorBlueprint.Plugins.MyPlugin/BlazorBlueprint.Plugins.MyPlugin.csproj

Step 4: Add it to the plugin list

One line in Plugins/Plugins.props — not in a host's .csproj:

<ItemGroup>
  <ProjectReference Include="$(MSBuildThisFileDirectory)MyPlugin\BlazorBlueprint.Plugins.MyPlugin\BlazorBlueprint.Plugins.MyPlugin.csproj" />
</ItemGroup>

Method 1: Project or package reference (the full-capability path)

Add the plugin to Plugins/Plugins.props, the one list every host imports:

<ItemGroup>
  <ProjectReference Include="$(MSBuildThisFileDirectory)MyPlugin\MyPlugin.csproj" />
</ItemGroup>

A PackageReference to a plugin published as a NuGet package works the same way for the assembly - it lands flat in the host's output either way, which is the only thing discovery cares about. Both give you what the drop-in folder cannot: static web assets, dependency conflicts caught at build time rather than at runtime, and a working debugger.

You do not add the reference again per host. Each host discovers plugins independently, so a plugin referenced by the web host alone would silently run no background work, serve no API under Full, and contribute no tables to the committed migrations — which is exactly why the reference lives in one shared file rather than in four .csproj files.

Method 2: Folder-based drop-in (adds a plugin without rebuilding the host)

For production or distribution, place plugin assemblies in the application's Plugins/ folder (next to the running Web app). When running from source, the loader also attempts to find Web/BlazorBlueprint.Web/Plugins/. Each plugin must live in its own sub-folder (the loader scans for Plugins/<PluginName>/*.dll, top-level DLLs only):

Web/BlazorBlueprint.Web/
└── Plugins/
    └── MyPlugin/
        ├── MyPlugin.dll
        ├── MyPlugin.deps.json
        └── [dependencies]

Every DLL in one sub-folder shares a single AssemblyLoadContext, so a plugin can sit beside its own private dependencies. A resolving handler probes that folder only after normal resolution fails, which keeps host-shared assemblies — IPlugin among them — unified through the default context. It is not version isolation: anything the host already has resolves from the host, so a plugin built against a different version of a shared package gets the host's.

Plugins are discovered once, at startup — there is no rescan and no hot-add. A DLL that appears later is invisible until you restart, and that is deliberate rather than a limitation: registration means RegisterServicesAsync, ConfigureWebAppAsync and DI wiring, none of which can be replayed against a container that is already built. A late registration could only ever produce a plugin that shows in the launcher and fails when opened.

Copy the plugin DLL and its private dependencies - not a whole dotnet publish output. A publish output carries the plugin's entire dependency closure, host assemblies included. Anything the host already ships is skipped on load - it has to resolve from the host, or the process ends up holding two copies of the same assembly and the plugin's IPlugin stops being the host's - so copying them achieves nothing but a bigger folder.

On PostgreSQL or SQL Server the plugin's tables do not exist yet, and a plugin does not arrive as a migration - so the tenant is gated rather than served a plugin that would fail on its first query. Set Database:AllowPluginSchemaDropIn so the guard creates the tables on the first request, or run the DbMigrator. MongoDB needs neither.

In Docker this needs a bind mount. The shipped compose files run the web container with read_only: true and mount nothing at /app/Plugins, so there is nowhere to put a DLL and nothing would survive the next compose up. Add a read-only mount to the web service - and to the background worker, if the plugin has sweeps:

    volumes:
      - ./plugins:/app/Plugins:ro

The mount is read-only, so read_only: true on the container stays intact - the operator writes on the host, beside the compose file. Treat write access to that directory as equivalent to write access to the application itself: plugins are fully-trusted in-process code.

Dependency versions: the host's copy always wins

A plugin and the host share one process, and for anything the host ships there is exactly one copy of the assembly - the host's. That is deliberate. The alternative, two same-named assemblies in different load contexts, means two different CLR types with one name: casts fail with the memorable Unable to cast object of type 'X' to type 'X', and any static state duplicates along with them.

Three rules follow for a plugin author:

• Reference the host's own assemblies with ExcludeAssets="runtime", so they are never copied into the plugin's output at all:

  <ProjectReference Include="..\..\Core\BlazorBlueprint.Application\BlazorBlueprint.Application.csproj"
                    ExcludeAssets="runtime" />

• Do not take a dependency on a different major version of anything the host ships. You will get the host's, and an incompatible API surfaces as a MissingMethodException at the point of use rather than at build time.
• Treat the host's Directory.Packages.props as the shared version contract. On the reference path NuGet resolves the graph for you and a genuine conflict fails the build (NU1605); on the drop-in path there is no build to catch it.

The host checks the last of those for you, in two halves. A plugin may declare Manifest.MinHostVersion, which PluginHostVersionRule enforces - but that is an explicit statement and only as good as the author's memory. So PluginContractVersionRule also reads the highest version of any BlazorBlueprint.* assembly the plugin was actually compiled against, straight out of its own reference table, and refuses to load it on an older host. That needs no cooperation, so it covers a third-party package and an author who forgot to raise their declared minimum.

Both skip the plugin rather than failing the boot: a plugin ahead of its host is a known state with an obvious fix, unlike an identity mismatch, which is silent and corrupting and is the one thing the host refuses to start on. Neither answers "too old" - the host is additive, and refusing an older build would mean rebuilding every plugin for every host patch release.

Installing a plugin is not the same as upgrading one

Installing works on every backend with no extra step. Upgrading — shipping a v2 that changes the plugin's own schema — always needs the DbMigrator or a rebuild, and nothing stops you deploying without it. That asymmetry is the sharpest edge in the plugin model, so it is worth knowing before you meet it.

The practical rule: run the DbMigrator whenever a plugin's version changes, not only when the host's schema does. It is idempotent, it exits non-zero if any tenant fails so a deploy gate can block on it, and on MongoDB it is the only thing that reconciles indexes for organisations that already had the plugin.

No backend validates indexes at run time, and that is a decision rather than an oversight — it applies to all three, not just Mongo. Only a missing unique index is a correctness problem; a missing ordinary one is merely slow. Index naming is generated and provider-specific, and this codebase deliberately diverges (GIN array indexes on Postgres, skipped entirely on SQL Server), so matching them is fragile — and a false positive would take a healthy organisation offline, which is worse than the gap.

Per-plugin flags

The host reads four independent flags per plugin, each keyed under Plugins:{full plugin id}. All four default to false in code, so a plugin that ships no configuration of its own is loaded and visible but installed by hand, per organisation. The last two override the plugin's own manifest (Scope and IsPremium).

The shape is identical wherever you write it — the plugin's own file, or a host's appsettings.json to override it:

"Plugins": {
  "BlazorBlueprint.Plugins.MyPlugin": {
    "AutoInstall": true,           // run SetupForOrganisationAsync for every new org created via
                                   // initial-setup or /Org/Select. false = the plugin is loaded
                                   // and visible in /Admin/PluginManagement, but org admins must
                                   // click Install manually per org.

    "Disabled": false,             // emergency kill switch. true = RegisterServicesAsync is
                                   // skipped, ConfigureWebAppAsync never runs, services are not in
                                   // DI. Existing orgs' OrganisationPlugins blob is preserved
                                   // but functionally inert. Disable a misbehaving plugin via
                                   // config + restart, no redeploy required.

    "PlatformOnly": false,         // true = surfaces only on the platform organisation: hidden from
                                   // every tenant org's plugin management, launcher and nav, never
                                   // auto-installed into a tenant, public routes 404 on tenant hosts.
                                   // Overrides the manifest's Scope.

    "RequiresSubscription": false  // true = premium app, gated behind a subscription plan (only
                                   // enforced when platform billing is on). Overrides the manifest's
                                   // IsPremium; an org needs an entitled plan to open it.
  }
}

Per-organisation install (PluginManagement admin)

1. Navigate to Plugin Management
2. Plugins listed under "Available" have not yet been installed for the current organisation. Plugins under "Installed" are already active.
3. Click Install on an Available plugin to run its SetupForOrganisationAsync for the current org — the plugin's per-org settings, role definitions, and any seeded entities are created.
4. Plugins flagged "AutoInstall": true appear under "Installed" automatically for orgs created after the flag was set; existing pre-flag orgs still need a manual Install click here.
5. The Disable button on an installed plugin removes the per-org entry from OrganisationPlugins but keeps the plugin globally loaded. Use the appsettings "Disabled": true flag for a global kill switch.

Platform plugin policy — the layer above appsettings

/Platform/PluginManagement carries two database-backed flags per plugin that override the appsettings values above, so an operator can change them at runtime without a redeploy:

• Available — a global soft off switch. When off, the plugin disappears from every organisation's launcher and nav, and its /plugin/{name}/* and /admin/plugin/{name}/* routes return 404 — for every org, including the platform one. Per-org install records and data are preserved untouched.
• AutoInstall — the same meaning as the appsettings key, resolved at runtime.

PlatformOnly and RequiresSubscription also appear there, read-only — those are resolved from appsettings and the manifest.

So there are three layers, and precedence runs database → appsettings → manifest default. Loaded (the DLL is present and not Disabled — a process-level kill that always wins) → platform policy (available / auto-install) → per-organisation install. If a plugin has vanished from one org's launcher, check per-org install; if it has vanished from every org, check Available before you go looking at config.

1. Plugin Isolation

• Don't modify core code - plugins should be self-contained
• Use interfaces for communication with core services
• Store all settings in the org's OrganisationPlugins document (tenant database, keyed by plugin Id) — derive your settings service from PluginSettingsServiceBase<TSettings>, which handles the caching, cloning and cache eviction for you

2. Error Handling

• Wrap all plugin operations in try-catch blocks
• Don't let plugin errors crash the application
• Log errors with appropriate log levels

Extension points beyond the lifecycle hooks

These are DI-registered providers rather than methods on IPlugin, for the same reason the section nav is: the host discovers them without referencing your assembly, so a new plugin never requires a host edit. Register them in RegisterServicesAsync.

Static assets

Your JS and CSS belong in your plugin's own wwwroot — each plugin is a Razor Class Library, so they are served at /_content/{YourAssembly}/…. Never put them in the host's wwwroot: it couples the host to your plugin and the file goes missing the moment the plugin is deployed as a drop-in DLL rather than a project reference.

<script type="module" src="/_content/BlazorBlueprint.Plugins.MyPlugin/my-page.js"></script>
<link rel="stylesheet" href="/_content/BlazorBlueprint.Plugins.MyPlugin/my-page.css" />

Per-plugin background service settings

Sweeps registered in RegisterBackgroundServicesAsync read their own configuration under your plugin's key, so an operator tunes them without touching host settings. Only the background-worker process binds these.

"Plugins": {
  "BlazorBlueprint.Plugins.MyPlugin": {
    "BackgroundServices": {
      "MyPluginRetention": { "Enabled": true, "ProcessingIntervalInSeconds": 21600, "MaxAgeInDays": 365 }
    }
  }
}

3. Route Conventions

• User-side pages: /plugin/{pluginname} for the main entry and /plugin/{pluginname}/{route} for every daily-use page. Render under MainLayout with the host's PluginSectionNav sidebar in place of the platform NavMenu. Anonymous-accessible plugin surfaces (e.g. /plugin/myplugin/publicpage/{id}) live in the same namespace.
• Admin / settings pages: /admin/plugin/{pluginname}/{route} — settings, setup wizards (when they fit the admin model), and configuration pages. Render under AdminLayout and are reached from the admin nav.
• Cross-section rule: pages under /plugin/{name}/* must not link to /admin/plugin/{name}/*. Reference admin pages by name in copy ("Admin → Plugins → My Plugin → Plugin settings") instead of an <a href> so the section split stays clean.
• Use kebab-case for route names.

4. Service Lifetime

• Use Scoped for request-specific services
• Use Singleton for shared state or cache
• Create scopes in background services using IServiceProvider

5. Data Access Conventions (Org vs Platform)

• Organisation-scoped data: use the normal tenant-scoped repository pattern (e.g. IRepository<T>) so reads/writes land in the current tenant database.
• Switch tenant context in background jobs: when a background service needs to iterate across organisations, it should: 1) fetch organisation metadata from the platform database (e.g. IPlatformRepository<Organisation>), 2) set ITenantContextSetter to the target organisation, then 3) run tenant-scoped queries using IRepository<T>.
• Plugin settings storage: per-org settings live in that organisation's OrganisationPlugins document — in the tenant database, keyed by plugin Id. Presence of a key means the plugin is both installed and enabled for the org. Platform-wide plugin settings are separate, in a single platform-database row.

Everything a Plugin Can Do

A full-featured plugin combines the extension points above into a single self-contained app. Across its Manifest and lifecycle hooks, one plugin can provide:

• ✅ In-plugin section navigation via IPluginSectionNavProvider
• ✅ Admin pages with different authorization levels
• ✅ Public and authenticated routes
• ✅ SignalR hubs with real-time communication (wired in ConfigureWebAppAsync, tenant-scoped with [HubOrganisationScoped])
• ✅ Plugin settings (per-organisation configuration)
• ✅ Background services (RegisterBackgroundServicesAsync, worker host only)
• ✅ Service registration and dependency injection
• ✅ Per-organisation setup and initialization
• ✅ Layout components (header, footer, or a floating overlay)