Embedded UI Architecture Reference

Embedded UI lets external web applications display Unqork modules on their own pages. To use it, a host page adds a single <script> tag from the Unqork server. That script registers a JavaScript API on window.unqork, creates a custom HTML element to hold the module, and starts the appropriate runtime (Centauri or Vega) inside a Shadow DOM boundary that keeps the module isolated from the host page's styles and scripts.

This reference covers the system architecture, file responsibilities, initialization sequence, and internal class hierarchy for Embedded UI.

Design Principles

These principles shape every technical decision in Embedded UI. Understanding them helps you predict system behavior and choose the right embedding approach for your use case.

Terminology

The following terms appear throughout this reference. Review these definitions before reading the technical sections below.

High-Level Component Diagram

This diagram displays the main components and how they connect at a high level. The host page loads a single script that sets up the runtime and manages all communication between the host and the embedded module.

graph TB
    subgraph "Host Page (External)"
        SCRIPT["<script src='embedded.js'>"]
        API["window.unqork.runtimes.default"]
        TARGET["<unqork-app> custom element"]
    end

    subgraph "embedded.js (Server-rendered Nunjucks)"
        RUNNER["IndexRunner.execute()"]
        UQR["UnqorkRuntime"]
        CR["CentauriRuntime"]
        VR["VegaRuntime"]
    end

    subgraph "Centauri Stack"
        CEMBED["centauri-embed.js"]
        LOADER["embed-loader.js"]
        SPA["spa-embed.js"]
        SHADOW["Shadow DOM"]
        ANG["Angular bootstrap"]
    end

    subgraph "Vega Stack"
        VAPI["runtimeApi.js"]
        VMOUNT["Vega mountModule()"]
    end

    SCRIPT --> RUNNER
    RUNNER --> UQR
    UQR -->|"v1.x module"| CR
    UQR -->|"v2.x module"| VR
    CR --> CEMBED
    CEMBED --> LOADER
    LOADER --> SPA
    SPA --> SHADOW
    SHADOW --> ANG
    VR --> VAPI
    VAPI --> VMOUNT
    API --> UQR
    TARGET --> SHADOW

Request Flow — Centauri Module

This sequence diagram traces the full loading and mounting flow for a Centauri module, from the host page's initial script request to the module rendering inside the Shadow DOM.

sequenceDiagram
    participant Host as Host Page
    participant EmbJS as embedded.js
    participant Server as Unqork Server
    participant CE as centauri-embed.js
    participant Shadow as Shadow DOM

    Host->>Server: GET /embedded.js?runtimeId=default
    Server-->>Host: Rendered index-js-express.njk (JS)
    Host->>EmbJS: IndexRunner.execute()
    Note over EmbJS: Creates UnqorkRuntime, sets window.unqork
    Host->>EmbJS: runtime.initialize()
    Host->>EmbJS: runtime.mountModule(moduleId, target)
    EmbJS->>Server: GET /fbu/form/:moduleId (detect runtime)
    Server-->>EmbJS: Module JSON (settings.runtimeVersion)
    Note over EmbJS: runtimeVersion=1.x → Centauri
    EmbJS->>Server: GET /centauri-embed.js
    Server-->>EmbJS: spa-embed.js + embed-loader.js
    Note over EmbJS: window.unqorkCentauri ready
    EmbJS->>Server: GET /auth/me
    Server-->>EmbJS: authUser object
    EmbJS->>CE: unqorkCentauri.mount(tagName, moduleId, config)
    CE->>Shadow: Create custom element + Shadow DOM
    CE->>Shadow: Load CSS into shadow
    CE->>Shadow: angular.bootstrap() inside shadow
    CE->>Shadow: $state.go('embedDisplay', { formId })
    Shadow->>Server: GET /fbu/roles, /fbu/form/{id}, /fbu/styles
    Shadow-->>Host: Module rendered inside unqork-app element

Core File Map

The following tables list every file involved in Embedded UI, grouped by role. Use this map to find the source of a specific behavior or to identify which file to modify for a given change.

Workflow-Specific Files

Iframe Embed Files

Test Files

Unit and Integration Tests

These files live in /src/app/__tests__/ and run with Jest.

Initialization and Boot Sequence

This section displays the step-by-step sequence that runs when Embedded UI loads. The flowchart covers everything from the initial script tag to the module mounting inside the host page.

flowchart TD
    A["Host page loads script tag"] --> B["Server renders index-js-express.njk"]
    B --> C["Injects: RUNTIME_VARS, __UQENV__, FEATURE_TOGGLES"]
    C --> D["IndexRunner.execute() runs"]
    D --> E["Creates UnqorkRuntime instance"]
    E --> F["Registers on window.unqork.runtimes[runtimeId]"]
    F --> G["Host calls runtime.initialize()"]
    G --> H["Host calls runtime.mountModule()"]
    H --> I{"Detect runtimeVersion"}
    I -->|"1.x"| J["CentauriRuntime.initialize()"]
    I -->|"2.x"| K["VegaRuntime.initialize()"]
    J --> L["Load centauri-embed.js"]
    K --> M["Load runtimeApi.js"]
    L --> N["unqorkCentauri.mount()"]
    M --> O["vegaApi.mountModule()"]

Server-Side Rendering

The Nunjucks template index-js-express.njk injects server-known values before the client-side JavaScript runs. The following variables configure the runtime to connect to the correct environment:

Class Hierarchy

window.unqork.runtimes.default  →  UnqorkRuntime
    ├── ._centauriRuntime       →  CentauriRuntime  (created lazily)
    │       └── ._centauriApi   →  window.unqorkCentauri  (set by embed-loader.js)
    └── ._vegaRuntime           →  VegaRuntime      (created lazily)
            └── ._runtimeApi    →  window.makeUnqorkApi()  (Vega SDK)

Runtime Detection

When mountModule({ moduleId }) is called, UnqorkRuntime fetches the module definition from /fbu/form/{moduleId} and inspects settings.runtimeVersion to decide which runtime to use:

Results are cached in UnqorkRuntime._moduleRuntimeCache (a Map), so repeat mounts of the same module skip the API call. The module definition fetched for detection is also passed to the internal runtime's mountModule(), avoiding a duplicate API request.

flowchart LR
    A["mountModule(moduleId)"] --> B["fetch /fbu/form/:moduleId"]
    B --> C{"runtimeVersion?"}
    C -->|"1.x"| D["CentauriRuntime.mountModule(moduleId, moduleData)"]
    C -->|"2.x"| E["VegaRuntime.mountModule(moduleId, moduleData)"]
    C -->|"missing"| D

Centauri Embedded — Three-Layer Architecture

The Centauri embedded mode uses three JavaScript files, each with a distinct role. The table below displays how they stack and each layer's responsibilities.

Angular States for Embed Mode

Embed mode registers its own set of UI-Router states inside the Shadow DOM so the embedded module can navigate between forms and workflow steps without modifying the host page's URL or routing tree. The table below lists each state, its URL pattern, the controller it uses, and how its template is provided.

Note: Workflow states use inline template (not templateUrl) because the HTTP interceptor prefixes relative URLs with hostUrl, which would cause $templateCache key mismatches.

Angular Services Decorated in Embed Mode

In embed mode, Angular services are decorated and HTTP interceptors are registered to prevent the embedded module from interfering with the host page. The table below lists the key modifications and their purpose.

Vega Embedded — Overview

The Vega embedded path is simpler because the Vega runtime API (runtimeApi.js) handles its own mounting and isolation. The host-facing API calls are identical to the Centauri path; the difference is internal.

flowchart LR
    A["VegaRuntime.initialize()"] --> B["appendScript(runtimeApi.js)"]
    B --> C["window.makeUnqorkApi(options)"]
    C --> D["VegaRuntime._runtimeApi ready"]
    D --> E["mountModule({ moduleId, target })"]
    E --> F["runtimeApi.mountModule()"]

File Dependency Graph

This diagram traces how each file depends on or loads another file. Use it to understand the relationship between the entry point script and the runtime-specific code.

graph TD
    NJK["index-js-express.njk (server)"] -->|renders| EMBJS["embedded.js"]
    EMBJS -->|creates| UQR["UnqorkRuntime"]
    UQR -->|creates| CR["CentauriRuntime"]
    UQR -->|creates| VR["VegaRuntime"]
    CR -->|loads| CEMBED["centauri-embed.js"]
    CEMBED -->|bundles| LOADER["embed-loader.js"]
    CEMBED -->|bundles| SPA["spa-embed.js"]
    SPA -->|imports| UTILS["embed-utils.js"]
    SPA -->|uses| ROUTES["index.route.js"]
    ROUTES -->|references| DW["displayWorkflow.js"]
    ROUTES -->|references| EDC["EmbedDisplayController.js"]
    DW -->|uses| WRRH["WorkflowResponseReceivedHandler.js"]
    VR -->|loads| VAPI["runtimeApi.js (external)"]