Document Generation Lifecycle

Uhuu documents are assembled from independently governed inputs. Keeping those inputs separate makes a document repeatable, reviewable, and safe to generate at scale.

BrandKit version + template revision + resolved data snapshot → document instance → renderer/editor

The browser renderer and the Uhuu SDK receive a resolved payload only. They must not fetch source systems, store connector credentials, or choose a different template or brand revision at render time.

Ownership

System	Owns	Does not own
BrandKit	Brand tokens, fonts, assets, governance, and published kit versions	Document layout or source-data execution
DataHub	Connector credentials, normalization, canonical output schemas, stream execution, and source provenance	Template layout or document rendering
Template Studio	Layout, semantic field bindings, template revisions, and authoring previews	Connector execution, credentials, or a second renderer
Document creation service	Resolving and recording a document instance from approved versions and a source snapshot	Authoring layout or connector configuration
uhuu-components, Document Editor, and SDK	Rendering and editing an already resolved document payload	Live data discovery or ungoverned brand changes

Stable inputs

Brand decision

A template references a published BrandKit and may carry a small, governed template-local token patch. It is not a copy of the kit.

Unpatched values inherit later published-kit updates; explicitly patched values remain intentional. BrandKit can lock token paths, in which case a template cannot patch them. A document instance records the resolved kit version and the permitted template patch used for that instance.

Template data binding

A DataHub-backed template contains a declarative binding, never source records or credentials. The current v1 shape is:

{
  "schema": "uhuu.template-data-binding.v1",
  "source": {
    "provider": "datahub",
    "teamId": "team_example",
    "streamId": "listings",
    "pipelineKey": "published",
    "outputSchema": {
      "id": "listing.v3",
      "version": "3",
      "hash": "sha256:<canonical-schema-digest>"
    }
  },
  "parameters": {
    "schema": { "type": "object" },
    "bindings": { "listingId": "request.listingId" }
  },
  "records": { "mode": "single", "selection": "request" },
  "mapping": { "listing.title": "listing.title" },
  "readiness": { "required": true, "maxAgeSeconds": 3600 }
}

mapping maps a template semantic path to a DataHub output path. Studio materializes identity entries for authored paths at publish time; a future mapping UI can add non-identity entries without changing the contract.

An authoring preview is deliberately different: it is bounded, redacted, and used only to help design and review a template. It is not published as the document's data source.

Creating an instance

The document-creation service resolves the binding server-to-server. It validates the tenant, parameters, output readiness, and expected output schema. On success, it records a source snapshot that includes the DataHub run ID, trace ID where available, pipeline version/hash, output-schema hash, record digest, and capture time.

It then records a uhuu.document-instance-plan.v1 containing:

• the pinned template ID, version, config hash, and runtime URL;
• the resolved BrandKit version and allowed template patch;
• the data-binding schema and immutable source snapshot reference; and
• approved locale and render flags.

The renderer/editor receives the safe resolved payload plus this pinned context. It does not call DataHub directly. This keeps an edited or regenerated document attributable to the exact template, brand, and source result that produced it.

Failure and recovery

Condition	Owner	Safe behavior	Recovery
Source output schema changed	DataHub + template owner	Do not create a document	Review/remap the binding, then publish a compatible template revision
Source result is stale	Document creation service	Do not silently use a newer result	Refresh the approved snapshot or use an explicitly retained snapshot
Output is not ready	DataHub	Do not create a partial document	Resolve the stream readiness issue and retry
A BrandKit path is locked	BrandKit	Reject the local patch	Use an allowed token, or change BrandKit governance intentionally
Dialog contract is incompatible	Editor/dialog release	Do not load unverified remote assets	Release a compatible dialog manifest and retry

Each failure should name its owning system and a recovery action. A retry must either use the same recorded snapshot or create a new, separately recorded plan; it must never silently switch to "latest" data.

Dialog support matrix

The platform supports dialog capabilities for custom templates through the Uhuu SDK and dialog documentation. Template Studio consumes the canonical dialog contract but intentionally supports only its curated authoring projection. For example, the legacy spreadsheet and dataloader dialog names remain valid for older platform templates, while Studio uses the canonical table dialog in new Builder artifacts.

Use the dialog type documented for your template integration. Do not infer Studio authoring support from a legacy platform dialog name.

Security rules

• Keep connector credentials, signed source URLs, and unredacted source records in DataHub or the document-creation service.
• Do not place connector configuration or live source URLs in a published template config, browser iframe, or SDK payload.
• Scope every cross-product request by the same teamId; use strings at the boundary.
• Treat a source snapshot and document instance plan as audit records. Retention and access follow the owning platform service's policy.

For the template-side payload/event contract, see the Uhuu SDK. For authoring a custom template locally, see Local development.