Skip to content

Frontend Architecture

This document defines Zakardo’s frontend architecture: the A2UI (Agent-to-User Interface) rendering system, the surface model, the component catalog, the streaming consumption pipeline, and how the frontend integrates with the Zakardo Runtime via the SDK. It covers how agent-generated UI is rendered, how developers customize the experience, and how the frontend handles the full intent lifecycle from submission to result display.

Prerequisites: This document assumes familiarity with Full-Stack Framework, Capability System (especially §7 Interaction Spec and §8 Anchored Views), Runtime API and SDK (especially §4 SSE and §15 Client SDK), Execution Engine, and Plan IR.


  1. Agent-driven, developer-owned. The agent decides what to show (via A2UI messages). The developer controls how it looks (via the component catalog and theme system).
  2. Surfaces, not pages. A2UI renders into named surfaces — regions of the application where agent content appears. Surfaces are declared by the developer and targeted by the agent.
  3. Two view modes. Anchored Views provide product-quality, pre-designed experiences for common outputs. Ephemeral Views are dynamically composed for everything else. The developer can incrementally upgrade views from ephemeral to anchored.
  4. Streaming-first. The frontend consumes SSE events progressively. Every phase of the intent lifecycle (planning, approval, execution, result) renders incrementally — never a spinner followed by a full-page dump.
  5. Framework-agnostic core. The A2UI rendering engine (@zakardo/a2ui) is framework-agnostic. React bindings (@zakardo/a2ui-react) are provided first-party. Vue, Angular, and Svelte bindings are possible.
  6. Themeable. Components use a design token system. Developers apply their existing design system rather than adapting to Zakardo’s styling.
  7. Type-safe end-to-end. A2UI messages are typed. Component props are typed. Data bindings between capability output and component props are validated at build time.

A Surface is a named region of the frontend where A2UI content is rendered. The developer declares surfaces when mounting the A2UI provider:

import { ZakardoProvider, Surface } from '@zakardo/a2ui-react';
function App() {
return (
<ZakardoProvider client={zakardoClient}>
<AppLayout>
{/* Sidebar: the "assistant" surface — chat-like agent interaction */}
<Sidebar>
<Surface name="assistant" />
</Sidebar>
{/* Main content: the "workspace" surface — rich data views */}
<MainContent>
<Surface name="workspace" />
</MainContent>
{/* Notification area: the "notification" surface — toasts and alerts */}
<Surface name="notification" position="top-right" />
</AppLayout>
</ZakardoProvider>
);
}
SurfacePurposeTypical PlacementContent
assistantConversational agent interfaceSidebar, drawer, or floating panelChat messages, plan previews, approvals, clarification prompts
workspaceRich data viewsMain content areaData tables, dashboards, detail views, forms
notificationTransient notificationsToast/snackbar areaSuccess messages, warnings, errors

Developers can define custom surfaces for domain-specific needs:

<Surface name="deal-pipeline" />
<Surface name="customer-360" />

When the Execution Engine completes a step and A2UI Composition generates messages, each message targets a specific surface:

// A2UI message (from SSE stream)
{
type: 'a2ui',
surface: 'workspace', // ← target surface
action: 'render', // render | update | clear
tree_id: 'tree_abc123', // unique identifier for this component tree
components: [...] // component tree to render
}

Messages targeting a surface that doesn’t exist are silently ignored (logged in development mode).

ActionBehavior
renderReplace the surface content with the new component tree
updatePatch the existing component tree (partial update)
appendAppend content below existing content (chat-style)
clearClear the surface

Every A2UI message follows this structure:

interface A2UIMessage {
/** Message type */
type: 'a2ui';
/** Target surface */
surface: string;
/** Action to perform on the surface */
action: 'render' | 'update' | 'append' | 'clear';
/** Unique identifier for this component tree (for update/clear targeting) */
tree_id: string;
/** The component tree to render (absent for 'clear' action) */
components?: A2UINode[];
/** Data context for data binding */
data?: Record<string, unknown>;
/** Metadata (execution context) */
meta?: {
execution_id: string;
step_index?: number;
capability?: string;
view_type: 'anchored' | 'ephemeral';
};
}

Each node in the component tree:

interface A2UINode {
/** Unique node ID within this tree */
id: string;
/** Component reference: { ComponentName: props } */
component: Record<string, Record<string, unknown>>;
/** Optional child node IDs (for layout components) */
children?: string[];
}

Component props can reference capability output data via dataPath expressions:

{
"id": "deal_count",
"component": {
"Metric": {
"label": "Open Deals",
"value": { "dataPath": "/deals/length" },
"format": "number"
}
}
}

The dataPath is a JSON Pointer (RFC 6901) into the data field of the A2UI message. Data binding is resolved by the A2UI renderer at render time.


Components are the building blocks of A2UI views. Every component referenced in an A2UI message must be registered in a catalog. Zakardo ships a Standard Catalog with common components. Developers extend it with custom components via packages/catalog.

The Standard Catalog (@zakardo/a2ui/catalog) ships with components for the most common data presentations:

ComponentDescriptionKey Props
ColumnVertical stackgap, children
RowHorizontal stackgap, align, children
GridCSS Grid layoutcolumns, gap, children
CardBordered container with optional header/footertitle, subtitle, children
TabsTabbed containertabs: [{ label, children }]
AccordionCollapsible sectionssections: [{ title, children }]
DividerHorizontal rulelabel
ComponentDescriptionKey Props
DataTableSortable, filterable tablecolumns, data, sortable, filterable, pageSize
DetailListKey-value pair listitems: [{ label, value }]
MetricSingle metric displaylabel, value, format, trend
MetricRowRow of metricsmetrics: [{ label, value, format }]
StatusBadgeColored status indicatortext, status (success, warning, error, info, neutral)
ProgressBarProgress indicatorvalue, max, label
TimelineChronological event listevents: [{ time, title, description }]
CodeBlockSyntax-highlighted codelanguage, code
JsonViewInteractive JSON treedata
ComponentDescriptionKey Props
ButtonClickable action buttonlabel, action, variant
FormForm with validationfields, onSubmit
TextInputText input fieldlabel, placeholder, value
SelectDropdown selectorlabel, options, value
CheckboxBoolean togglelabel, checked
ConfirmConfirmation dialogtitle, message, confirmLabel, cancelLabel
ComponentDescriptionKey Props
TextRich text (Markdown)content, variant (body, heading, caption)
AlertColored alert bannertype (info, success, warning, error), title, message
EmptyEmpty state placeholdericon, title, description, action
LoadingLoading skeletonlines, variant
ImageImage displaysrc, alt, width, height

Developers create custom components in packages/catalog for domain-specific visualizations:

packages/catalog/src/components/DealPipeline.ts
import { defineA2UIComponent } from '@zakardo/a2ui';
export default defineA2UIComponent({
name: 'DealPipeline',
description: 'Kanban board visualization for deal stages',
propsSchema: {
stages: { type: 'array', items: { type: 'string' }, required: true },
deals: { type: 'array', items: { type: 'object' }, required: true },
onDealClick: { type: 'action', required: false },
},
// React implementation
render: 'DealPipelineRenderer',
});
packages/catalog/src/components/DealPipelineRenderer.tsx
import type { A2UIComponentProps } from '@zakardo/a2ui-react';
export function DealPipelineRenderer({
stages,
deals,
onDealClick,
}: A2UIComponentProps<'DealPipeline'>) {
return (
<div className="deal-pipeline">
{stages.map((stage) => (
<div key={stage} className="pipeline-column">
<h3>{stage}</h3>
{deals
.filter((d) => d.stage === stage)
.map((deal) => (
<div key={deal.id} className="deal-card" onClick={() => onDealClick?.(deal)}>
<strong>{deal.name}</strong>
<span>${deal.value.toLocaleString()}</span>
</div>
))}
</div>
))}
</div>
);
}

Custom catalogs are registered in packages/catalog/src/catalog.ts:

import { defineCatalog } from '@zakardo/a2ui';
import DealPipeline from './components/DealPipeline';
import CustomerCard from './components/CustomerCard';
export default defineCatalog({
name: 'my-crm-catalog',
extends: 'zakardo-standard', // Inherit all standard components
components: {
DealPipeline,
CustomerCard,
},
});

When the A2UI renderer encounters a component reference, it resolves it in this order:

  1. Custom catalog (packages/catalog) — if the capability’s anchored_view.catalog or the project config specifies a custom catalog.
  2. Zakardo Standard Catalog — the default fallback.

If a component is not found in any catalog, the renderer displays an error boundary in development and a fallback Text component in production.


Anchored Views are pre-designed component trees declared on capabilities (see Capability System §8). They provide product-quality, pixel-perfect rendering for frequently-used outputs.

When a step completes and it has an Anchored View:

  1. A2UI Composition loads the Anchored View’s component tree from the capability definition.
  2. Resolves all dataPath bindings against the capability’s output data.
  3. Emits an A2UI message targeting the declared surface with meta.view_type: 'anchored'.

Example — “Show open deals” capability with Anchored View:

User: "Show me all open deals"
→ Planner → Plan (1 step: list_open_deals)
→ Execution → list_open_deals completes → output: { deals: [...], summary: { total: 12 } }
→ A2UI Composition detects anchored_view on list_open_deals
→ Loads pre-defined DataTable + MetricRow layout
→ Binds /deals → DataTable.data, /summary/total_label → Metric.value
→ Emits A2UI message → surface: "workspace"
→ Frontend renders polished deals dashboard

When a capability does not have an Anchored View, A2UI Composition dynamically assembles a view from the capability’s output schema:

  1. Inspects the output data shape.
  2. Selects appropriate Standard Catalog components:
    • Array of objects → DataTable
    • Single object → DetailList
    • Scalar → Metric
    • Nested → Card with recursion
  3. Applies default layout (Column wrapper).
  4. Emits the A2UI message with meta.view_type: 'ephemeral'.

Ephemeral Views are “good enough” for most outputs. Developers can upgrade any ephemeral view to an Anchored View by adding an anchored_view declaration to the capability.

The assistant surface (chat-style) receives a different class of A2UI messages:

EventAssistant Surface Rendering
intent.receivedShown as user message bubble
planner.thinkingLoading indicator with “Planning…”
planner.clarificationQuestion card with options
planner.conversationAgent response bubble
plan.awaiting_approvalPlan Review card (see §6)
execution.step_startedProgress indicator
execution.step_completedStep completion checkmark
execution.gate_triggeredGate approval card
execution.completedSuccess message with link to workspace view
execution.failedError card with trace link

The frontend renders the full intent lifecycle progressively via SSE events. Each phase of the lifecycle maps to specific UI states:

Intent Submitted → Show user message + loading
│
▼
Planning → Show "Planning..." indicator
│
├── CLARIFY → Show question + options (user responds)
├── CONVERSE → Show agent response (no plan)
│
▼
Plan Generated → Show plan steps as a checklist
│
▼
Awaiting Approval → Show Plan Review card with approve/reject
│
├── Rejected → Show rejection message
│
▼
Execution Started → Animate plan steps: ◯→●→✓
│
├── Gate → Show gate approval UI
├── Interaction → Show interaction form
├── Retry → Show retry status
│
▼
Execution Complete → Show success + results (workspace surface)

When a plan requires approval (plan.awaiting_approval), the assistant surface shows a Plan Review card:

// Rendered by the SDK's React hooks
<PlanReview
plan={{
steps: [
{ index: 0, capability: 'list_customers', description: 'List all churned customers', effectClass: 'READ' },
{ index: 1, capability: 'send_email_batch', description: 'Send recovery email', effectClass: 'WRITE_EXTERNAL' },
],
summary: 'This plan will find all churned customers and send them a recovery email.',
effectSummary: 'READ (1 step), WRITE_EXTERNAL (1 step)',
estimatedDuration: 5000,
}}
validationResult={{ valid: true, checks: [...] }}
onApprove={() => stream.approve()}
onReject={(reason) => stream.reject(reason)}
/>

The Plan Review card shows:

  1. Step list — each step with its capability name, description, and effect class (color-coded).
  2. Effect summary — aggregated risk level.
  3. Validator results — pass/fail checks from the Validator (see Validator Specification §6.2).
  4. Estimated duration — from Plan IR metadata.
  5. Approve/Reject buttons.

When a gate is triggered during execution (execution.gate_triggered):

<GateApproval
gate={{
gateId: 'gate_step2_write',
stepIndex: 1,
capability: 'send_email_batch',
reason: 'WRITE_EXTERNAL capability requires approval',
approverRoles: ['manager', 'admin'],
}}
onApprove={(comment) => client.respondToGate(executionId, gate.gateId, 'approve', comment)}
onDeny={(comment) => client.respondToGate(executionId, gate.gateId, 'deny', comment)}
/>

When a capability requires user input (execution.interaction_required):

<InteractionForm
interaction={{
stepIndex: 2,
capability: 'select_pricing_tier',
formSchema: {
fields: [
{
name: 'tier',
type: 'select',
label: 'Pricing Tier',
options: ['basic', 'pro', 'enterprise'],
},
{ name: 'confirmed', type: 'checkbox', label: 'I confirm this selection' },
],
},
context: 'The customer is eligible for all pricing tiers. Please select one.',
}}
onSubmit={(response) => client.respondToInteraction(executionId, 2, response)}
/>

The form schema is derived from the capability’s Interaction Spec (see Capability System §7).


The React integration provides hooks, components, and context for rendering A2UI content in React applications:

npm install @zakardo/a2ui-react
import { ZakardoProvider } from '@zakardo/a2ui-react';
import { ZakardoClient } from '@zakardo/sdk';
import catalog from '@my-app/catalog';
const client = new ZakardoClient({
baseUrl: '/zakardo/v1',
});
function App() {
return (
<ZakardoProvider client={client} catalog={catalog}>
<MyApp />
</ZakardoProvider>
);
}

Manages the full intent lifecycle:

const {
submit, // (request: IntentRequest) => void
status, // 'idle' | 'planning' | 'awaiting_approval' | 'executing' | 'completed' | 'failed'
stream, // Stream controller (approve, reject, cancel)
plan, // Plan data (when status is 'awaiting_approval')
steps, // Step progress array (during execution)
result, // Execution result (when completed)
error, // Error (when failed)
a2uiMessages, // Array of A2UI messages received
} = useZakardoIntent();

Subscribes to an existing execution’s progress:

const { status, steps, events, result, a2uiMessages } = useZakardoExecution(executionId);

Accesses the current content state for a specific surface:

const {
trees, // Active component trees on this surface
lastUpdate, // Timestamp of last update
} = useA2UISurface('workspace');

Renders all A2UI content targeted at a named surface:

<Surface
name="workspace"
fallback={<EmptyWorkspace />} // Shown when surface has no content
className="my-workspace" // Custom CSS class
/>

Renders a specific A2UI component tree:

<A2UIRenderer tree={a2uiMessage.components} data={a2uiMessage.data} catalog={catalog} />

Pre-built assistant surface with chat UI:

<ChatAssistant
placeholder="Ask me anything..."
onSubmit={(message) => intent.submit({ message })}
showPlanPreview={true}
showExecutionProgress={true}
/>

This is a convenience component that combines <Surface name="assistant"> with an input field, message history, plan review cards, and execution progress. It can be used as-is or as a reference for custom implementations.


A2UI components use CSS custom properties (design tokens) for all visual properties. Developers override tokens to apply their design system:

/* Base theme (shipped with @zakardo/a2ui) */
:root {
--z-color-bg: #ffffff;
--z-color-bg-secondary: #f9fafb;
--z-color-text: #111827;
--z-color-text-secondary: #6b7280;
--z-color-border: #e5e7eb;
--z-color-primary: #3b82f6;
--z-color-success: #10b981;
--z-color-warning: #f59e0b;
--z-color-error: #ef4444;
--z-font-family: 'Inter', system-ui, sans-serif;
--z-font-size-sm: 0.875rem;
--z-font-size-base: 1rem;
--z-font-size-lg: 1.125rem;
--z-radius-sm: 0.375rem;
--z-radius-md: 0.5rem;
--z-radius-lg: 0.75rem;
--z-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--z-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
--z-spacing-xs: 0.25rem;
--z-spacing-sm: 0.5rem;
--z-spacing-md: 1rem;
--z-spacing-lg: 1.5rem;
}

A2UI ships with built-in dark mode via a .zakardo-dark class on the provider:

<ZakardoProvider client={client} theme="dark">
<MyApp />
</ZakardoProvider>

Or auto-detect from the system preference:

<ZakardoProvider client={client} theme="auto">
import { defineTheme } from '@zakardo/a2ui';
const myTheme = defineTheme({
colors: {
primary: '#6366f1', // Indigo
success: '#22c55e',
bg: '#0f172a', // Slate-900
text: '#f1f5f9', // Slate-100
},
fonts: {
family: "'JetBrains Mono', monospace",
},
radius: {
md: '0.25rem', // Sharper corners
},
});
<ZakardoProvider client={client} theme={myTheme}>

Packaged Actions are pre-built, one-click actions that bypass the expressed intent flow. They appear as buttons, quick actions, or context menu items in the frontend:

┌─────────────────────────────────────────┐
│ Quick Actions │
│ ┌──────────┐ ┌──────────┐ │
│ │ + Customer│ │ New Deal │ │
│ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │Send Report│ │ Run Sync │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────┘

Packaged Actions are defined via the SDK’s configuration:

import { definePackagedActions } from '@zakardo/a2ui-react';
export const quickActions = definePackagedActions([
{
id: 'quick_create_customer',
label: 'New Customer',
icon: 'user-plus',
description: 'Create a new customer record',
action: {
action_id: 'quick_create_customer',
// Parameters can be pre-filled or collected via a form
parameterForm: {
fields: [
{ name: 'name', type: 'text', label: 'Name', required: true },
{ name: 'email', type: 'email', label: 'Email', required: true },
],
},
},
placement: ['sidebar', 'command-palette'],
},
]);

The frontend discovers available packaged actions via:

  1. Static registration (above) — developer-defined in the frontend codebase.
  2. Runtime API — capabilities that declare packaged_action configurations are discoverable via GET /zakardo/v1/capabilities?packaged=true.

When the user clicks a packaged action:

  1. If the action has parameterForm, show the form first.
  2. Submit as a packaged mode intent to the Runtime API.
  3. Follow the standard SSE lifecycle (planning is skipped — packaged actions map directly to known capabilities).

The frontend consumes SSE events through a layered pipeline:

SSE Connection (EventSource or SDK)
│
▼
Event Router ← Routes events by type
│
├── Intent events → Intent State Machine
├── Planner events → Planner State
├── Execution events → Execution State Machine
├── A2UI events → Surface Router
└── Error events → Error Handler
Surface Router
│
├── assistant surface → Chat message stream
├── workspace surface → A2UI Renderer
└── notification → Toast notifications

SSE reconnection is handled automatically by the SDK:

  1. Browser EventSource auto-reconnects with Last-Event-ID.
  2. The SDK reconnects SSE with the last received event_id.
  3. Server replays missed events from the Event Store (see Execution Engine §4.5).
  4. State machines reconcile replayed events with current state.

For non-SSE clients (mobile, CLI), the SDK falls back to the polling endpoint (GET /executions/:id/events, see Runtime API §5.6).

For interactive actions (gate approvals, interaction responses), the frontend applies optimistic updates:

  1. User clicks “Approve” on a gate.
  2. Frontend immediately shows “Approved” state.
  3. SDK sends POST /executions/:id/gate/:gateId in the background.
  4. If the server returns an error, the frontend reverts to the previous state and shows an error.

apps/web/
├── src/
│ ├── main.tsx # React entry point
│ ├── App.tsx # Root component (Provider, Surface layout)
│ ├── components/
│ │ ├── layout/
│ │ │ ├── AppLayout.tsx # Main layout (sidebar + workspace)
│ │ │ ├── Sidebar.tsx
│ │ │ └── Header.tsx
│ │ ├── assistant/
│ │ │ ├── ChatPanel.tsx # Custom assistant surface implementation
│ │ │ ├── MessageList.tsx
│ │ │ └── InputBar.tsx
│ │ ├── workspace/
│ │ │ └── WorkspaceView.tsx # Custom workspace surface wrapper
│ │ └── foundation/ # Non-Zakardo pages (billing, admin, etc.)
│ │ ├── Dashboard.tsx
│ │ └── Settings.tsx
│ ├── styles/
│ │ ├── theme.css # Design token overrides
│ │ └── global.css
│ ├── config/
│ │ ├── zakardo-client.ts # SDK client initialization
│ │ └── packaged-actions.ts # Packaged action definitions
│ └── router.tsx # React Router config
├── public/
├── index.html
├── vite.config.ts
├── package.json
└── tsconfig.json
packages/catalog/
├── src/
│ ├── components/
│ │ ├── DealPipeline.ts # Component definition
│ │ ├── DealPipelineRenderer.tsx # React renderer
│ │ ├── CustomerCard.ts
│ │ ├── CustomerCardRenderer.tsx
│ │ └── index.ts
│ ├── catalog.ts # Catalog registration
│ └── index.ts
├── package.json
└── tsconfig.json

All A2UI components in the Standard Catalog meet WCAG 2.1 AA standards:

RequirementImplementation
Keyboard navigationAll interactive components (buttons, forms, tables) are keyboard-accessible
Screen readersARIA labels, roles, and live regions for dynamic content
Focus managementFocus moves logically when surfaces update
Color contrastAll token-based colors meet 4.5:1 contrast ratio
Motion reductionRespects prefers-reduced-motion media query

When A2UI messages update a surface, the renderer:

  1. Uses aria-live="polite" regions for non-critical updates.
  2. Uses aria-live="assertive" for error notifications.
  3. Manages focus: new content does not steal focus unless it’s interactive (e.g., gate approval).

OptimizationHow
Tree diffingA2UI renderer diffs component trees (by id). Only changed nodes re-render.
Lazy catalog loadingCustom catalog components are code-split. Standard Catalog is tree-shaken.
VirtualizationDataTable with 1000+ rows uses virtual scrolling.
MemoizationData binding resolution is memoized per tree_id + data hash.
PackageTarget Size (gzipped)
@zakardo/a2ui (core)< 15 KB
@zakardo/a2ui-react (bindings)< 8 KB
Standard Catalog (all components)< 40 KB
Standard Catalog (tree-shaken, typical)< 20 KB

DecisionResolution
Surface modelNamed regions where A2UI content renders. Developer declares surfaces; agent targets them. Not route-based — multiple surfaces can be active simultaneously.
Two view modesAnchored Views (pre-designed, product quality) and Ephemeral Views (dynamically composed, good enough). Developers incrementally upgrade.
Component catalogStandard Catalog ships with 25+ components. Developers extend with custom catalog in packages/catalog. Catalogs are composable.
Framework-agnostic core@zakardo/a2ui is pure TypeScript. @zakardo/a2ui-react provides React bindings. Other framework bindings are possible.
Design token themingCSS custom properties for all visual properties. Dark mode built-in. Custom themes via defineTheme.
Chat-style assistantThe assistant surface is chat-oriented with progressive rendering. Plan previews, gate approvals, and interactions render inline.
Streaming-firstAll rendering is SSE-driven. No full-page loads. Every lifecycle phase renders incrementally.
Optimistic UIInteractive actions (approve, deny, respond) are optimistic. Server errors trigger rollback.
Packaged ActionsOne-click shortcuts that bypass expressed intent. Defined in frontend or discovered from capabilities.
AccessibilityWCAG 2.1 AA compliance for all Standard Catalog components.

QuestionDeferred To
How do A2UI components handle real-time data updates (live dashboards)?Real-time Data Specification (future)
How are A2UI components tested in isolation?Testing and Validation Specification (addendum)
How does the mobile SDK render A2UI on native platforms?Mobile SDK Specification
What are the exact animation specifications for transitions?Implementation detail
How does A2UI handle multi-tenant branding?PRD — Zakardo Cloud
How does the registry marketplace distribute custom catalogs?Registry and Marketplace Specification