Plugin System Overview

The Plugin System is SCRIPE's extensibility engine. It allows platform operators to install certified Tier 1 plugins that run in-process with full infrastructure access, and third-party Tier 2 plugins that run in a sandboxed REST gateway with an isolated key-value data store.

What Is the Plugin System?

The Plugin System provides a Two-Tier architecture for extending SCRIPE with additional capabilities. Tier 1 plugins are trusted, certified modules that integrate directly into the .NET runtime via IPluginStartup. Tier 2 plugins are third-party applications that integrate via a secure REST gateway and communicate with the host using a postMessage-based SDK.

• Tier 1 — Certified Plugins

  In-process plugins with full DI access, Module Federation frontend, and IPluginStartup contract.

• Tier 2 — Sandboxed Plugins

  Third-party plugins isolated via REST gateway with rate limiting, scoped auth tokens, and an isolated key-value store.

• Plugin SDK

  postMessage-based communication protocol with typed bridge classes for theme, auth, navigation, and toast.

• API Gateway

  Authenticated plugin-api gateway with per-tenant rate limiting, execution logging, and API key management.

• Execution Logs

  Append-only execution log per installation. Records endpoint, duration, status code, and success/failure.

• Webhook Events

  7 platform events (installed, uninstalled, activated, deactivated, upgraded, health failed, rate limited).

Two-Tier Comparison

The Two-Tier model separates trusted internal plugins from third-party marketplace plugins with clear security boundaries.

System Architecture

The plugin system orchestrates from catalog registration through lifecycle management, health monitoring, and execution logging.

Plugin Registration Lifecycle

Plugins transition through formal registration stages from manifest validation and sandbox testing to production publication.

Backend Architecture

The backend follows SCRIPE's standard 3-project Clean Architecture module layout: Plugins.Domain → Plugins.Application → Plugins.Infrastructure.

public abstract class PluginsDbContext : DbContext
{
    public DbSet<PluginDefinition>         PluginDefinitions         { get; set; }
    public DbSet<PluginVersion>            PluginVersions            { get; set; }
    public DbSet<PluginInstallation>       PluginInstallations       { get; set; }
    public DbSet<PluginPermissionGrant>    PluginPermissionGrants    { get; set; }
    public DbSet<PluginDataStore>          PluginDataStores          { get; set; }
    public DbSet<PluginApiKey>             PluginApiKeys             { get; set; }
    public DbSet<PluginWebhookSubscription>PluginWebhookSubscriptions{ get; set; }
    public DbSet<PluginExecutionLog>       PluginExecutionLogs       { get; set; }
}

CQRS Commands & Queries

The Plugins module registers 15 request handlers via AstraFlow.Mediator. All commands have a corresponding FluentValidation validator.

Domain Entities

The Plugins domain defines 8 entities. PluginExecutionLog is append-only (Entity<Guid>); all others are AuditableEntity<Guid> with soft-delete support.

Frontend Architecture

The frontend follows SCRIPE's MVVM pattern with strict layer separation. Views are dumb UI; ViewModels handle all state and mutations via TanStack Query.

src/modules/plugins/
├── di.ts                              # DI container (PluginService → PluginRepository)
├── index.ts                           # Public exports (views, components, viewmodels)
└── src/
    ├── domain/
    │   ├── entities/                  # PluginCatalogItem, PluginInstallation,
    │   │                              #   PluginDefinition, PluginManifest
    │   └── interfaces/                # IPluginRepository, IPluginService
    ├── data/
    │   ├── models/PluginModels.ts     # API DTOs + PagedResult<T>
    │   ├── mappers/PluginMapper.ts    # DTO ↔ Entity conversion
    │   ├── repositories/              # PluginRepository (implements IPluginRepository)
    │   └── services/                  # PluginService (Axios via IApiService)
    └── presentation/
        ├── viewmodels/                # usePluginCatalogViewModel
        │                              # useInstalledPluginsViewModel
        │                              # usePluginSettingsViewModel
        │                              # usePluginLogsViewModel
        ├── views/                     # PluginCatalogView, InstalledPluginsView
        │                              # PluginSettingsView, PluginLogsView
        └── components/                # PluginCard, PluginInstallDialog
                                       # PluginHealthBadge

Plugin SDK

The Plugin SDK lives in src/core/plugins/ and provides all infrastructure for host-plugin communication via iframe postMessage for Tier 2, and Module Federation for Tier 1.

src/core/plugins/
├── plugin-sdk/
│   ├── types.ts               # HostToPluginMessage | PluginToHostMessage
│   ├── PluginBridge.ts        # postMessage channel (origin-validated)
│   ├── PluginFrame.tsx        # iframe host component
│   ├── PluginThemeSync.ts     # dark/light/accent/RTL push to iframe
│   ├── PluginAuthRelay.ts     # scoped token delivery on request
│   ├── PluginNavigationBridge.ts  # iframe → host router.push()
│   ├── PluginToastBridge.ts   # iframe → host toast notifications
│   └── PluginEventBus.ts      # in-process plugin event dispatcher
├── plugin-host/
│   ├── usePluginHost.ts       # manages active plugin bridge map
│   └── PluginHostProvider.tsx # React context wiring all bridges
└── tier1/
    ├── federation-config.ts   # Module Federation shared deps manifest
    └── ModuleFederationLoader.tsx  # runtime loader for Tier 1 remotes

API Endpoints

All plugin endpoints are under /api/v1/plugins/ for admin operations and /api/v1/plugin-api/v1/ for the sandboxed Tier 2 gateway.

Webhook Events

The Plugin System publishes 7 webhook events that third-party systems can subscribe to via the webhook subscription API.

Background Jobs

Three background jobs manage plugin health, data cleanup, and soft-delete purging.

Permissions Reference

All plugin endpoints are protected by permission-based authorization. Permissions are seeded at startup by PluginsPermissionProvider.

Quick Start Guide

1. 1

   Run Database Migration

   Create the Plugins module database and apply migrations using the SCRIPE CLI.
   Shell

   Copy

   scripe db add-migration Initial -m Plugins
   scripe db update -m Plugins

2. 2

   Register a Plugin Definition

   Register your plugin in the catalog by calling the definitions endpoint as super admin.
   JSON

   Copy

   POST /api/v1/plugins/definitions
   {
     "key": "my-plugin",
     "name": "My Plugin",
     "nameAr": "مكوني",
     "description": "A test plugin",
     "descriptionAr": "وصف",
     "tier": 2,
     "scope": 1,
     "baseUrl": "https://plugin.example.com",
     "frontendUrl": "https://plugin.example.com/ui",
     "manifestJson": "{\"key\":\"my-plugin\",\"version\":\"1.0.0\",\"tier\":\"tier2\"}"
   }

3. 3

   Install for a Tenant

   Install the plugin for a specific tenant using the install endpoint.
   JSON

   Copy

   POST /api/v1/plugins/install
   {
     "pluginDefinitionId": "<definitionId>",
     "tenantId": "<tenantId>",
     "installedByUserId": "<userId>"
   }

4. 4

   Activate the Installation

   Activate the installation to make it available to users.
   HTTP

   Copy

   POST /api/v1/plugins/installed/{installationId}/activate?tenantId={tenantId}

5. 5

   Open the Plugin UI

   Navigate to /plugins/installed in the frontend. You will see the plugin with its health badge, and can click Settings or Logs for per-installation views.

Security

The Plugin System enforces multiple security boundaries to protect tenants from malicious or buggy plugins.

• ✅

  Do

  • Validate event.origin in every iframe message listener
  • Use the plugins_definition.create permission for catalog registration
  • Store sensitive config in SettingsJson (encrypted at rest)
  • Monitor execution logs for unusual latency spikes
• ❌

  Don't

  • Allow iframe navigation to external (non-/) paths
  • Store raw API keys in the database (only KeyHash is stored)
  • Grant plugins_definition.create to non-admin roles
  • Disable the PluginSandbox rate limiter in production