SuperModel Architecture

SuperModel achieves zero server inference through a carefully designed layered architecture where every decision point uses MCP sampling to delegate reasoning to the client’s LLM.

Core Architecture Diagram

Three-Layer Architecture

SuperModel operates through three distinct layers, each using MCP sampling to maintain zero server inference:

Layer 1: Request Processing & Routing

Purpose: Analyze incoming requests and determine which UI tool should handle them.

Request Reception

Gateway receives user request through standard MCP tool call

Routing via Sampling

Gateway uses MCP sampling to ask client’s LLM: “Which tool should handle this request?”

Route Decision

Client’s LLM analyzes available tools and returns routing decision

Example Routing Sampling Request:

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [{
      "role": "user",
      "content": {
        "type": "text",
        "text": "User request: 'Create a product search interface'\n\nAvailable tools:\n- product-search-ui: E-commerce search with filters\n- data-viz-ui: Charts and analytics\n- form-builder-ui: Dynamic forms\n\nWhich tool should handle this? Return JSON."
      }
    }],
    "systemPrompt": "You are a routing assistant. Return only JSON: {\"tool\": \"tool-name\", \"params\": {...}}"
  }
}

Layer 2: Gateway Pattern & Tool Orchestration

Purpose: Route requests to the appropriate specialized UI generation tool based on sampling decisions. The gateway implements a pattern inspired by mcp-agent and mcp-use, but with critical differences:

Traditional Agent Routing
SuperModel Routing

// Traditional: Server uses its own LLM for routing
const decision = await serverLLM.decide(request);
const tool = selectTool(decision);

Cost: $$$ (Server pays for LLM inference)

// SuperModel: Server uses client's LLM via sampling
const decision = await gateway.sample(routingPrompt);
const tool = selectTool(decision.content);

Cost: $0 (Client’s LLM handles all reasoning)

Tool Registry Configuration:

{
  "tools": {
    "product-search-ui": {
      "description": "E-commerce product search with filters and shopping cart",
      "capabilities": ["search", "filter", "cart", "checkout"],
      "templates": ["product-grid", "search-results", "shopping-cart"]
    },
    "data-viz-ui": {
      "description": "Interactive charts and data visualization",
      "capabilities": ["charts", "tables", "analytics", "dashboards"],
      "templates": ["line-chart", "bar-chart", "data-table", "dashboard"]
    }
  }
}

Layer 3: UI Generation & Packaging

Purpose: Generate AG-UI compatible components and package them as MCP-UI resources.

Tool Execution

Selected tool processes the request and determines specific UI requirements

UI Generation via Sampling

Tool uses MCP sampling to generate AG-UI component code

Code Validation

Tool validates generated code for security and AG-UI compatibility

MCP-UI Packaging

Tool wraps generated UI as MCP-UI resource with proper MIME type

UI Generation Sampling:

{
  "method": "sampling/createMessage", 
  "params": {
    "messages": [{
      "role": "user",
      "content": {
        "type": "text",
        "text": "Generate AG-UI product search component. Requirements:\n- Product grid with images\n- Price and brand filters\n- Sort options\n- Add to cart buttons\n\nData: [{\"id\": \"1\", \"name\": \"Wireless Headphones\", \"price\": 199}...]\n\nUse AG-UI event system for all interactions."
      }
    }],
    "systemPrompt": "Generate complete AG-UI React component. Include proper event handlers.",
    "maxTokens": 2000
  }
}

Zero-Inference Guarantee

SuperModel maintains its zero-inference guarantee through several architectural principles:

Deterministic Server Logic

All server operations are deterministic. The server executes decisions made by the client’s LLM rather than making its own decisions.

Sampling-Only AI

Every point where AI reasoning is needed uses MCP sampling to delegate to the client’s LLM.

Stateless Tools

UI generation tools are stateless and only execute based on explicit instructions from sampling responses.

Context Passthrough

Context flows through the system without server-side interpretation or modification.

Framework Modularity

SuperModel is designed to support multiple generative UI frameworks through adapter patterns:

interface GenUIAdapter {
  generateComponent(prompt: string, context?: any): Promise<ComponentCode>;
  validateComponent(code: string): SecurityReport;
  packageForMCP(component: ComponentCode): MCPUIResource;
}

class AGUIAdapter implements GenUIAdapter {
  async generateComponent(prompt: string, context?: any) {
    // AG-UI specific generation logic
    const samplingResponse = await this.gateway.sample({
      messages: [{ role: "user", content: { type: "text", text: prompt } }],
      systemPrompt: "Generate AG-UI React component with event handlers"
    });
    
    return {
      code: samplingResponse.content.text,
      framework: 'ag-ui',
      events: this.extractAGUIEvents(samplingResponse.content.text)
    };
  }
  
  packageForMCP(component: ComponentCode): MCPUIResource {
    return {
      type: 'resource',
      resource: {
        uri: `ui://ag-ui/${Date.now()}`,
        mimeType: 'application/vnd.mcp-ui.ag-ui',
        text: component.code
      }
    };
  }
}

// Future framework support
class NextGenUIAdapter implements GenUIAdapter {
  // Implementation for future generative UI framework
}

Next Steps

Zero-Inference Deep Dive

Learn how SuperModel eliminates server inference costs completely.

Gateway Pattern

Understand intelligent routing and tool orchestration.

Hello World Example

See the architecture in action with a simple calculator example.

Multi-App Workflows

Explore complex user journeys across multiple UI apps.

Getting Started

Core Concepts

Examples

Architecture

SuperModel Architecture

Core Architecture Diagram

Three-Layer Architecture

Layer 1: Request Processing & Routing

Layer 2: Gateway Pattern & Tool Orchestration

Layer 3: UI Generation & Packaging

Zero-Inference Guarantee

Deterministic Server Logic

Sampling-Only AI

Stateless Tools

Context Passthrough

Framework Modularity

Next Steps

Zero-Inference Deep Dive

Gateway Pattern

Hello World Example

Multi-App Workflows

​SuperModel Architecture

​Core Architecture Diagram

​Three-Layer Architecture

​Layer 1: Request Processing & Routing

​Layer 2: Gateway Pattern & Tool Orchestration

​Layer 3: UI Generation & Packaging

​Zero-Inference Guarantee

Deterministic Server Logic

Sampling-Only AI

Stateless Tools

Context Passthrough

​Framework Modularity

​Next Steps

Zero-Inference Deep Dive

Gateway Pattern

Hello World Example

Multi-App Workflows

SuperModel Architecture

Core Architecture Diagram

Three-Layer Architecture

Layer 1: Request Processing & Routing

Layer 2: Gateway Pattern & Tool Orchestration

Layer 3: UI Generation & Packaging

Zero-Inference Guarantee

Framework Modularity

Next Steps