Plugin Architecture
How a Pomavo plugin fits together: the host application, the sandboxed widget iframe, your plugin backend, and the trust boundary between them.
Overview
A Pomavo plugin never runs inside the host. It is a separate, self-hosted web service that the platform talks to over a small, well-defined contract. Three pieces cooperate across a trust boundary: the host application, a sandboxed widget rendered in the browser, and your plugin backend.
The diagram below shows how a request moves through the system. Everything to the left of the boundary is Pomavo; everything to the right is code you write and host.
The Pieces
Host App
The Pomavo browser application. It renders your widgets inside sandboxed iframes, hands each one a short-lived token plus the current context, and POSTs lifecycle events to your backend.
Sandboxed Widget
Your React UI, loaded into an isolated iframe. It uses the PomavoBridge from @pomavo/sdk/client to read context, token, settings, and theme - and to auto-resize.
Plugin Backend
Your Node service. It verifies the host token with the shared secret, serves your widget bundles and data endpoints, and optionally calls Pomavo with the PomavoClient.
Pomavo Platform & API
Issues lifecycle events and short-lived tokens, and exposes the REST API your backend reads and writes through an integration API key.
How a Request Flows
The numbered connectors in the diagram correspond to the lifecycle of an installed plugin:
Lifecycle event + shared secret
When an organization installs your plugin, Pomavo POSTs an installed event to your lifecycle.url, carrying an installationId and a sharedSecret. You store the secret and use it to verify every later request. The same channel delivers updated and uninstalled events.
The host embeds your widget
Each widget you declare in the manifest is loaded into a sandboxed iframe at the URL you provide. The host hands the iframe a short-lived token and the current context - such as the ticket being viewed - over the PomavoBridge.
Your widget calls your backend
The widget fetches your own API endpoints, passing the host token as a Bearer credential. Your backend verifies the token with the shared secret and resolves the org, user, and ticket from it - the iframe never trusts data it cannot prove.
Your backend can call Pomavo
If your plugin needs to read or write Pomavo data, it uses the PomavoClient with an integration API key delivered during installation. This is the only path back into the platform, and it is fully audited.
Why the Boundary Matters
The widget runs in a sandboxed iframe with no direct access to host memory, cookies, or the Pomavo API. It can only act through tokens it is given, and your backend is the only component that holds long-lived credentials. This keeps a misbehaving or compromised plugin contained to its own surface area.
Because the host and your plugin only ever exchange signed tokens and explicit events, you can deploy, update, and scale your plugin independently of Pomavo. Nothing about your implementation - language, framework, hosting - is visible to the platform.