UI Rendering Engine
The Server-Driven UI layer behind approval screens and other engine-generated forms in TotalApp. Instead of hand-coding a screen for every table or form combination another engine needs, this engine describes the screen as a small JSON tree, which the frontend renders instantly using a shared, theme-aware component catalog.
What Is the UI Rendering Engine?
When the Matrix Agent finishes scoring a vendor, a lead, or a compliance record, a human often still needs to review the result before it becomes final — approving a purchase order, confirming a lead is ready to hand to sales, signing off on a compliance finding. Each of these moments needs a small, focused screen: a few read-only fields, a status badge, one confirmation button. Building a dedicated frontend page for every one of these moments, across every module that might need one, would mean writing (and maintaining) dozens of nearly-identical screens by hand.
The UI Rendering Engine solves this with a Server-Driven UI approach: instead of a frontend developer writing a new page for every screen, the backend describes the screen as a JSON tree of components — a form containing an input, a badge, a button — and hands that description to the frontend. The frontend reads the tree once and turns it into a fully working, styled screen immediately, without a page-specific code change on either side.
Styling never travels inside that JSON tree. Every component only carries a semantic role — primary, success, danger — and a shared, theme-aware catalog on the frontend resolves that role into actual colors and spacing at render time. This is what lets every tenant's brand colors apply automatically, without the engine ever needing to know what those colors are.
In one sentence
Other engines describe a screen as data — inputs, a badge, a button — and this engine hands that description to the frontend, which turns it into a working, on-brand screen without anyone writing a dedicated page for it.
How It Works — Describe, Don't Hand-Code
Every screen produced by this engine follows the same three-stage path from "something needs review" to "a working screen on the user's device":
| Stage | What happens |
|---|---|
| 1. Build the Schema | The engine takes the record that needs review — an order, a scored vendor, a flagged compliance item — and builds a small tree of components describing the screen: a form, containing a status badge, one or two read-only fields showing the record's key details, and a confirmation button. |
| 2. Send It as JSON | That component tree is returned as plain JSON — no HTML, no styling, no tenant-specific colors. Every component names only what it is (an input, a button) and what role it plays (a primary action, a success badge). |
| 3. Render on the Device | The frontend's renderer walks the tree and, for every component, looks up its semantic role in a shared style catalog to resolve the actual classes to paint with. A tenant's own brand colors apply automatically, since the catalog — not the schema — is where colors live. |
Why keep styling out of the schema entirely?
If the backend baked in actual colors or Tailwind classes, every tenant with a different brand palette would need its own copy of the schema-building logic — and every future theme would mean touching every screen-generating code path across every engine. By only ever naming a semantic role, the same schema renders correctly for every tenant and every theme; only the frontend's catalog needs to know what "primary" or "success" actually looks like.
Input — What a Screen Request Carries
To build an approval screen, the engine needs just the record's own key facts — nothing about how the screen should look:
Record Identifier
The order number, vendor ID, or record reference this screen is about — shown to the reviewer as a read-only field so they know exactly what they're confirming.
Key Value
The single most important number tied to the record — a total price, a score, a due amount — surfaced prominently so the reviewer doesn't have to look it up elsewhere.
AI Verification Flag
Whether an upstream engine (typically Matrix Agent) already verified this record automatically — shown as a status badge so the reviewer knows how much of the work is already done.
Never sent: colors, spacing, or layout
A request to build a screen never includes styling information of any kind. If a tenant's brand colors change, or a component's default style changes app-wide, no request payload anywhere needs to change — only the frontend's shared style catalog does.
Output — A Component Tree, Ready to Render
The engine's response is a small tree of typed nodes, each one of a handful of supported component kinds:
| Component | What it represents |
|---|---|
| Form | The outer container for a screen — holds every other component that belongs to this particular review. |
| Input | A single labeled field, typically shown as read-only since the reviewer is confirming a decision rather than editing raw data. |
| Badge | A small status pill — for example, showing whether the record was already verified by an upstream AI step. |
| Button | The action the reviewer takes to finish the screen — almost always a single confirmation button per screen. |
| Table | A reserved component kind for screens that need to show a list of related rows rather than a handful of single fields. |
Every component carries a semantic variant, never a literal color
A Button or Badge only ever declares a role like primary, success, or danger. The frontend's shared style catalog is the single place that decides what each of those roles actually looks like for the current tenant and theme.
How End Users Actually Use It
Confirming an AI-Scored Record
When Matrix Agent finishes scoring a vendor or lead and a human needs to sign off before it counts as final, the reviewer sees a small, focused screen — the record's key details, a badge showing it was already AI-verified, and one button to confirm. There is nothing to configure and nothing extra to learn; the screen is built specifically for that one decision.
Getting a New Approval Step Live Quickly
When a new module needs its own "please confirm this" moment, it doesn't wait on a new frontend page being designed and built — it asks this engine for a schema describing the fields it needs shown, and a working, on-brand screen exists as soon as that request is wired in.
Where the UI Rendering Engine Fits
This engine doesn't score, audit, or process anything on its own — it turns another engine's finished result into a screen a human can act on:
| Source Engine | What gets rendered |
|---|---|
| Matrix Agent | A scored vendor, lead, or compliance record that needs a human's final confirmation before it's treated as approved. |
| Integration & Webhook Engine | An incoming order or record from an external platform that needs a quick human review before it's pushed onward (for example, into an ERP system). |
| Audit Agent | A flagged finding from a document review that needs a reviewer to confirm or dismiss it. |
Like the Event & Analytics Engine, every screen this engine builds quietly reports its own generation as a tracked event — so a schema that fails to build shows up in the same usage and health history as everything else in TotalApp.
A shared layer other engines call into, not a screen you configure
This engine has no dedicated settings screen of its own — other engines call it when they need a review step, and the resulting screen appears immediately. There is nothing to turn on; if an engine is wired to request a schema from it, that screen is already available.