Skip to main content

Generated UI development setup

The renderer belongs to the BFF. Complexity handles generation, persistent state, and history. No separate renderer service or hosted Gateway is required. Use Docker development for ordinary startup.

Dependencies and package patch​

The backend pins @openuidev/lang-core@1.0.1. The BFF pins that package and @openuidev/react-lang@1.0.1. Install with each repository's package manager and lockfile.

BFF patches/@openuidev__react-lang@1.0.1.patch and workspace patchedDependencies are installation inputs. The patch removes automatic external-CDN loading of development DevTools while preserving renderer exports. Do not edit node_modules manually.

Optional OPENUI_TELEMETRY_DISABLED=1 applies to dependency installation. It is not a required application .env input. Exact package release-age exceptions do not authorize a wider version range. Check both packages, lockfiles, patch, parser, and registry contract together during an update.

Database and Prisma​

Canonical SQL files reside under mailGen/ECS_MovePST_To_TempSQL/DB_Lib/Sql/. The schema setup uses this order:

  1. 20261015_complexity_ui_states.sql: complexity.ui_states, output/revision unique key, and message foreign key.
  2. 20261015_complexity_ui_state_groups.sql: nullable link_group_id, revision-scoped group unique key, and identity CHECK.
  3. 20261016_complexity_ui_state_tool_ids.sql: colon support in canonical tool/output IDs, preserving equality and the 200-character limit.
  4. 20261016_complexity_submit_input.sql: nullable complexity.chats.submit_input_enabled boolean. Existing NULL means OFF in the application.
  5. 20261016_complexity_ui_state_revisions.sql: positive UI revisions instead of the known earlier ui_revision = 1 condition. answer_revision > 0 and version > 0 remain.

Use the deployment's normal controlled schema path. scripts/apply-local-database-migrations.sh applies guarded migrations in its matching local Compose environment. Other runtimes/test instances need their own verified schema path. Prisma schema synchronization does not install SQL CHECK constraints by itself.

The revision upgrade stops for an unknown or unvalidated CHECK. Reapplying the already-correct positive CHECK leaves it unchanged. The change adds no column, backfill, or Prisma mapping. EF mapping and fresh-install CHECK use positive revisions too.

After state/group/submit mapping changes, generate backend and BFF Prisma clients from their own schemas. A CHECK-only revision change does not itself require new model names or fields.

Before an upgrade, inspect scope and the offline schema-preservation difference. Preserve state/chat rows, unique keys, indexes, and foreign keys. Stop on destructive or unknown differences. Reset, volume deletion, --accept-data-loss, and --force-reset are not upgrade steps.

Services and grants​

BFF, Complexity service, and Getter must use a compatible source contract. Admin manages the Submit input policy catalog. Refresh Admin when that catalog changes.

The intended group's Agent tool access needs separate displayOpenUI and displayMarkdown grants. Tool registration and old saved settings do not grant runtime access.

Persistent state uses the existing owner-encryption/conversion path. Linked groups use their own authenticated associated data. No separate infrastructure service, credential, bucket, or port is needed. Saving UI state does not call a model. Sending it to the model requires Submit input.

Generation policy and prompt defaults​

Use matching BFF, Complexity, and Admin source for policy/default changes. In Admin LLM configuration, distinguish built-in defaults from tenant overrides. Updates do not automatically rewrite tenant prompts or snapshots from existing runs.

New inline generation and retained legacy history rendering follow display behavior. A prompt-default change alone needs no schema migration or new environment variable.

After startup, use a disposable conversation to check generation, interaction, reload, old revisions, and language display. See generated UI usage and installation requirements.

Startup checks for persistent UI state​

During unified Docker initialization, Prisma schema synchronization precedes the database feature installer. The seed step follows the installer. A normal restart that skips initialization does not repeat these steps.

The installer supplies three canonical CHECK constraints on complexity.ui_states:

  • ui_states_revision_check: answer_revision, ui_revision, and CAS version must each be positive. CAS means compare-and-swap, the version check for concurrent updates.
  • ui_states_identity_check: tool_call_id must equal output_id. The identity accepts 1–200 ASCII letters, digits, underscores, colons, or hyphens.
  • ui_states_group_identity_check: link_group_id can be NULL. Otherwise, it accepts 1–200 ASCII letters, digits, underscores, or hyphens.

The installer adds a missing CHECK and validates every existing row. It leaves an identical, validated CHECK unchanged, including its PostgreSQL object identifier (OID). It replaces only the exact known legacy revision or tool/output identity definition under the expected constraint name.

An unknown definition, an unvalidated constraint, or a different constraint type stops the transaction and initialization. Row validation failure also stops initialization. Inspect the actual database catalog and existing rows before a retry. Do not bypass these checks or use destructive startup flags.

Prisma continues to manage the relational objects: tables, columns, indexes, unique keys, and foreign keys. The SQL files above remain the canonical explicit upgrade definitions.

For an isolated instance, use its own verified schema path. Do not use the legacy scripts/apply-local-database-migrations.sh target lookup for that instance. That script selects PostgreSQL through the backend's legacy Coolify Compose file, its environment file, and COMPOSE_PROJECT_NAME. Its infrastructure wrapper also loads the backend environment. It does not establish the isolated instance's target from its runtime snapshot.