Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supermodel.network/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
1

Request Reception

Gateway receives user request through standard MCP tool call
2

Routing via Sampling

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

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: Server uses its own LLM for routing
const decision = await serverLLM.decide(request);
const tool = selectTool(decision);
Cost: $$$ (Server pays for LLM inference)
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.
1

Tool Execution

Selected tool processes the request and determines specific UI requirements
2

UI Generation via Sampling

Tool uses MCP sampling to generate AG-UI component code
3

Code Validation

Tool validates generated code for security and AG-UI compatibility
4

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.