Plugin System & Catalog

Every plugin implements the IPlugin interface, which defines the contract between the plugin and the Phoenix.Core host. This interface provides lifecycle hooks for service registration, database model configuration, and application startup.

public interface IPlugin {
    string Name { get; }
    string Schema { get; }
    void RegisterServices(WebApplicationBuilder builder);
    void OnStartup(WebApplication app);
    void OnModelCreating(ModelBuilder builder);
    Type[] GetAdditionalDatabaseTypes();
}

A PluginBase abstract class provides sensible defaults for optional members, so most plugins only need to override the methods they actually use.

Each plugin specifies its own database entities, API endpoints, pipelines, and frontend code. This isolation means plugins can be developed, tested, and deployed independently without modifying core platform code.

Plugins are registered in a specific order within Startup.cs using the fluent .AddPhoenixPlugin<>() chain. Registration order determines initialization sequence and can affect dependency resolution.

builder
    .AddPhoenixPlugin<SitePlugin>()
    .AddPhoenixPlugin<ConnectCorePlugin>()
    .AddPhoenixPlugin<PaymentsPlugin>()
    .AddPhoenixPlugin<InvoicingPlugin>()
    .AddPhoenixPlugin<SalesPlugin>()
    .AddPhoenixPlugin<ProductsPlugin>()
    .AddPhoenixPlugin<NetSuitePlugin>()
    .AddPhoenixPlugin<NuveiPlugin>();

Initialization Sequence

Workflow Taxonomy

Connector plugins use WorkflowVendor and WorkflowProduct properties to categorize their pipelines within the workflow engine. This taxonomy enables the platform to route workflows to the correct connector implementation.

Plugins are managed as Git submodules within the host project. Understanding Git fundamentals is essential to working with this architecture, so let us walk through the key concepts.

Git Basics: Commits

A Git repository is fundamentally a sequence of commits. Each commit is a snapshot of your project at a point in time, identified by a unique hash (SHA). Commits form a chain, where each commit points back to its parent.

Branch References

A branch is simply a pointer (reference) to a specific commit. The HEAD pointer indicates which branch you currently have checked out.

Creating Commits

When you create a new commit, Git creates a new snapshot and moves the current branch pointer forward. The branch always points to the latest commit on that line of development.

Creating Branches

Creating a branch simply adds a new pointer to the current commit. You can then switch to it and start making independent changes without affecting the original branch.

Branch Divergence

When commits are made on different branches, the branches diverge. Each branch has its own line of history, and they can later be merged back together.

What Are Submodules?

A Git submodule is a reference to another Git repository embedded within your project. Rather than copying code, the parent repository stores a pointer to a specific commit in the submodule's repository. This means the submodule's code lives in its own repository with its own history, branches, and pull requests—but it appears as a folder in your project.

Submodule Status

When a submodule has changes or is pointing to a different commit than what the parent expects, git status will show the submodule as modified. The status shows the submodule folder with a special notation indicating the commit reference has changed.

Working with Submodules

git submodule update --init

git submodule foreach git pull origin develop

Follow these steps to add a new plugin as a Git submodule and integrate it into both the backend and frontend.

1

Get the Clone URL from Azure Repos

Navigate to the plugin repository in Azure DevOps and click the Clone button to get the HTTPS URL.

Click the Clone button

Copy the HTTPS URL

git submodule add <CLONE_URL> Plugins/Phoenix.YourPlugin

4

Add to Visual Studio Solution

In Visual Studio, right-click the solution and select "Add Existing Project" to include the plugin's .csproj file.

5

Add Project Reference

Add a project reference from the client/host project to the plugin project so it compiles and links correctly.

builder.AddPhoenixPlugin<YourPlugin>();

{
  "plugins": [
    "phoenix-site",
    "phoenix-payments",
    "phoenix-your-plugin"
  ]
}

Updating Submodule References

When a plugin has been updated in its own repository, you need to update the submodule reference in the parent project. Navigate into the submodule directory, pull the latest changes, then go back to the parent and commit the updated reference.

Hundreds of plugins are available for the Clarity platform across five categories: Core, Feature, Connector, Provider, and Build. Below is a handful of the most common plugins; many more are available to review and discuss upon request.

Plugin Dependency Graph

The dependency structure radiates outward from Phoenix.Core. Core plugins have direct dependencies, while feature plugins, connectors, and providers depend on both Core and the relevant core plugins.