Asset Sync and Notifications

Lyntaris uses an event-driven sync path. Lyntaris is the source of truth and exposes a WebSocket hub that broadcasts change events. Unity and FastAPI subscribe to those events and then pull the data they need.

This eliminates periodic polling while still keeping the data flow pull-based and deterministic.

WebSocket endpoint

Lyntaris serves the notify hub on the same host:

• Local dev: ws://127.0.0.1:3000/ws
• Production: wss://<lyntaris-host>/ws

Query parameters:

• pipeline: target pipeline (default kiosk). Use all or * to receive all pipelines.
• clientId: optional identifier for logs.
• secret: optional auth token (see below).

Headers:

• X-Notify-Secret: <secret> (preferred if your client can set headers).

Authentication

The hub is strict by default and will refuse to start unless a valid secret is set.

• ASSETS_NOTIFY_SECRET is required (32+ chars and not CHANGE_ME).
• For dev-only bypass: ASSETS_NOTIFY_ALLOW_INSECURE_DEV=true.

If the hub starts without a valid secret, it will log a warning and accept unauthenticated connections only when the dev bypass flag is enabled.

Event shape

All events use a single payload shape:

{
  "type": "assetsChanged",
  "pipeline": "cc",
  "changed": [
    "text/MainPrompt.md",
    "qanda/metadata.json",
    "vector-databases/images/metadata.json"
  ],
  "version": "2026-01-02T12:34:56.789Z"
}

Notes:

• pipeline can be null for broadcast events.
• changed[] contains paths relative to the pipeline root (not absolute filesystem paths).
• Chatflow changes are emitted as chatflows/<id>.

Debounce behavior

Lyntaris batches rapid edits before sending events.

• Default: ASSETS_NOTIFY_DEBOUNCE_MS=10000
• Override per environment in .env.

Prompting storage modes

Prompting can be routed to draft or published storage depending on the host:

• PROMPTING_STORAGE_MODE=draft|published|auto
• PROMPTING_STORAGE_DIR_DRAFT (default prompting-draft)
• PROMPTING_STORAGE_DIR_PUBLISHED (default prompting-published)
• PROMPTING_DRAFT_HOSTS (default localhost,127.0.0.1,host.docker.internal)

When PROMPTING_STORAGE_MODE=auto, writes from draft hosts go to draft storage; everything else goes to published storage. The notify hub emits events for the storage being written.

What each consumer does

Unity:

• Refresh prompting caches when changed[] contains prompting paths (for example text/, speech/, qanda/metadata.json).
• Refresh agents/chatflows when changed[] contains chatflows/.

FastAPI:

• Refresh vector database ingestion when changed[] contains:
  • vector-databases/images/metadata.json
  • vector-databases/videos/metadata.json
  • qanda/metadata.json

Q&A uses InputJsonQandA.json as the ingest payload, while qanda/metadata.json is the sync signal to reduce autosave churn.