Declarative Site Adapters

Site Adapters are JSON configurations that tell the Appilot extension how to behave on a specific web application. They solve a fundamental challenge: not all web apps work the same way.

The Problem

Standard web applications change their URL when users navigate between pages. Appilot uses URL patterns to match knowledge content to the current page. But some frameworks — like Vaadin, GWT, or Ext JS — are single-page applications where the URL never changes. Form elements may be wrapped in Shadow DOM, and every user action triggers a server roundtrip.

Without adapters, the extension cannot:

• Know which page the user is on
• Find form fields inside Shadow DOM
• Interact with framework-specific components

The Solution

A Site Adapter provides structured rules — no code execution, just configuration that the extension runtime interprets:

Configuration	Purpose	Example
runtime.shadow_dom_max_depth	How deep to traverse Shadow DOM	6 for Vaadin (default: 3)
runtime.action_timeout_ms	Wait time for DOM updates after actions	3000 for server-roundtrip apps
page_detection.rules	DOM-based view identification	Read menu bar text to determine current view
interaction_overrides	Custom interaction strategies per component	Open-then-select for combo boxes
knowledge_hints	Cross-cutting retrieval hints	Always include domain_global scope

Schema

{
  "schema_version": "1.0",
  "domain": "your-app.example.com",
  "framework_hints": ["vaadin"],
  "runtime": {
    "shadow_dom_max_depth": 6,
    "action_timeout_ms": 3000,
    "mutation_observer_debounce_ms": 500
  },
  "page_detection": {
    "strategy": "dom_selector",
    "rules": [
      {
        "selector": "vaadin-menu-bar [selected]",
        "read": "innerText",
        "map": {
          "Online Services": { "view_path": "zufi/online-services" }
        }
      }
    ]
  },
  "interaction_overrides": {},
  "knowledge_hints": {
    "always_include_scopes": ["domain_global"]
  }
}

Page detection resolves to a view_path that matches a row in the views table seeded for the domain. Knowledge entries are linked to views via the content_views junction, so retrieval is driven by view identity.

How It Works

1. Extension loads on a domain
2. Fetches adapter config from GET /apps/domains/adapter/lookup?domain=<hostname>
3. Caches locally (5-minute TTL)
4. Applies runtime overrides (Shadow DOM depth, timeouts)
5. Uses page detection rules to identify the current view (resolved to a view_path)
6. Retrieves knowledge content linked to that view via content_views
7. Uses interaction overrides for framework-specific components

Extensibility

The strategy fields are extension points. Currently supported:

• Page detection: dom_selector — reads DOM elements to determine current page
• Interaction: open_then_select — for combo boxes that need a click to open

Future strategies can be added without schema changes — the extension dispatches to handlers based on the strategy name.

API Endpoints

Method	Endpoint	Auth	Purpose
GET	/apps/domains/adapter/lookup?domain=<name>	Public	Extension fetches config
GET	/apps/domains/:id/adapter	JWT	Read adapter for a domain
PUT	/apps/domains/:id/adapter	JWT	Update adapter config