Architecture

Understanding UICP's architecture will help you build robust and scalable UI-enhanced AI applications.

System Overview

UICP follows a modular architecture with clear separation of concerns:

┌─────────────┐
│  AI Agent   │
└──────┬──────┘
       │
       │ Queries available components
       ↓
┌─────────────────────┐
│  UI Bridge API      │
│  (@uicp/tools)      │
└──────┬──────────────┘
       │
       │ Returns component schemas
       ↓
┌─────────────┐
│  AI Agent   │
└──────┬──────┘
       │
       │ Generates UICP block
       ↓
┌─────────────────────┐
│  Parser             │
│  (@uicp/parser)     │
└──────┬──────────────┘
       │
       │ Validates & extracts
       ↓
┌─────────────────────┐
│  Component Registry │
└──────┬──────────────┘
       │
       │ Retrieves component
       ↓
┌─────────────┐
│  Renderer   │
└─────────────┘

Core Packages

@uicp/parser

The parser is responsible for:

  • Extracting UICP blocks from AI responses
  • Parsing XML-like component definitions
  • Validating props against component schemas
  • Type coercion and data transformation

@uicp/tools

The tools package provides:

  • Component Registry for managing available components
  • UI Bridge API for AI agent integration
  • Schema introspection utilities
  • Component metadata management

Data Flow

1. Component Discovery

AI agent calls list_ui_components() to discover available UI components and their capabilities.

2. Schema Retrieval

For specific components, agent calls get_component_schema(name) to understand required and optional props.

3. Generation

Based on context and user intent, agent generates a UICP block with appropriate component and props.

4. Parsing & Validation

Parser extracts the block, validates against schema, and coerces types as needed.

5. Rendering

Component is rendered in the chat interface with validated props.

Design Principles

  • Type Safety: Leverage TypeScript and Zod for runtime validation
  • Extensibility: Easy to add new components without modifying core
  • Framework Agnostic: Core logic independent of UI framework
  • Developer Experience: Intuitive APIs and clear error messages

Next: Learn about Component Definitions to understand how to create your own components.