Plugin Platform — Overview

What this is

This PR (feat/plugin-sdk, #361 "SDK V1") adds a third-party plugin platform to Dentolize: a way for outside developers — dental lab networks, imaging/PACS vendors, insurance clearinghouses, payment gateways, marketing tools — to build their own service that plugs into a clinic's Dentolize account without Xolize writing a bespoke integration for each one.

A plugin is not code that runs inside Dentolize. It's an external application that the developer hosts themselves. A clinic installs it from an in-app Plugin Hub, and from then on the plugin talks to Dentolize over a scoped REST API and receives signed webhook events — the same shape of integration model used by Stripe, Shopify, or Slack apps.

This is a large, foundational PR: 320 files touched, a new npm package (@dentolize/plugin-sdk), 6 new database models, ~60 new REST endpoints across 30+ resources, 32 permission scopes, 44 webhook event types, a clinic-facing management UI, and a separate internal Xolize admin tool for reviewing and publishing plugin listings.

Why it exists

Dental clinics already use a constellation of point tools around their practice-management software — lab ordering portals, WhatsApp/SMS reminder services, insurance clearinghouses, payment gateways, imaging devices. Before this PR, every one of those integrations required a custom, one-off connection built and maintained by Xolize. The plugin platform inverts that: Xolize builds the access-control, consent, and delivery machinery once, and partners build against a stable, versioned, self-service API.

The moving pieces, in one paragraph

Xolize (or, once a self-serve flow exists, a partner directly) creates a plugin listing in a registry — name, description, requested data scopes, requested webhook events, an optional settings form. Xolize reviews and publishes it. A clinic owner finds it in the in-app Plugin Hub, reviews exactly what data it will access in plain language, accepts a data processing agreement, and installs it. Installation mints a scoped API token and, when the plugin registers one, a webhook signing secret. From then on the plugin's own backend calls Dentolize's REST API (/api/v1/...) with that token, and Dentolize pushes it signed webhook events in near-real time. Everything is scoped per-installation: a plugin can only see what the clinic consented to, and only for that one clinic.

What's genuinely new vs. what's reused

New: the Plugin, PluginInstallation, PluginToken, WebhookEndpoint, WebhookEvent, and WebhookDelivery database models; the entire /api/v1 REST surface (30 controllers under packages/server/src/plugins/api/); the webhook signing/delivery/retry pipeline (packages/server/src/plugins/webhooks/); the @dentolize/plugin-sdk npm package; the clinic-facing Plugin Hub UI (packages/clinic-web-canary/src/features/PluginHub/); and the internal Xolize plugin-registry admin tool (packages/clinic-web/src/components/admin/plugins/).

Reused, not reinvented: tenancy isolation rides the platform's existing ~65 getWhereFor* synthetic-context helpers, so a plugin request is authorized the same way an internal GraphQL request is; the money paths (external payment recording, payment links) reuse the real payment core, so a plugin-recorded payment behaves identically to one entered by a receptionist.

Status as shipped in this PR

Per the platform's own internal roadmap (docs/plugin-platform/api-expansion-roadmap.md), Waves 1–3 are shipped on this branch: 32 scopes, 44 event types, 57 OpenAPI paths, SDK 0.4.0. That covers platform basics (clinic/branches/practitioners/procedures directories, settings), clinical integrations (labs, imaging, forms, prescriptions, encounters/vitals, quotations), and revenue integrations (claims, online payments, e-invoicing, external payment recording). A fourth wave (CRM, comms, loyalty, inventory, bookkeeping, BI) is documented as a proposal only — nothing from Wave 4 is implemented in this PR.

There is currently no self-serve developer portal — new plugin listings are created by Xolize staff through an internal admin tool (see Plugin registry (Xolize admin)).

Where to go next

• Walkthrough — a screenshot-driven tour of installing and configuring a plugin as a clinic owner.
• How plugins work — the business and technical model end to end.
• Scopes & consent — what data a plugin can see, and how a clinic controls that.
• By team pages — how each part of the org should talk about, sell, support, or test this.