> ## 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.

# Architecture

> Understanding SuperModel layered zero-inference architecture

# SuperModel Architecture

SuperModel achieves zero server inference through a carefully designed layered architecture where every decision point uses [MCP sampling](https://modelcontextprotocol.org) to delegate reasoning to the client's LLM.

## Core Architecture Diagram

```mermaid
graph TD
    Client[MCP Client with LLM] --> Gateway[SuperModel Gateway]
    Gateway --> Router[Sampling Router]
    Router --> |MCP Sampling| Client
    Router --> Tools[UI Generation Tools]
    Tools --> |MCP Sampling| Client
    Tools --> Packager[MCP-UI Packager]
    Packager --> AGUIBridge[AG-UI Bridge]
    AGUIBridge --> Client
    
    style Client fill:#6366F1,color:#fff
    style Gateway fill:#8B5CF6,color:#fff
    style Tools fill:#A855F7,color:#fff
```

## 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.

<Steps>
  <Step title="Request Reception">
    Gateway receives user request through standard MCP tool call
  </Step>

  <Step title="Routing via Sampling">
    Gateway uses MCP sampling to ask client's LLM: "Which tool should handle this request?"
  </Step>

  <Step title="Route Decision">
    Client's LLM analyzes available tools and returns routing decision
  </Step>
</Steps>

**Example Routing Sampling Request**:

```json
{
  "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](https://github.com/lastmile-ai/mcp-agent) and [mcp-use](https://mcp-use.com), but with critical differences:

<Tabs>
  <Tab title="Traditional Agent Routing">
    ```typescript
    // Traditional: Server uses its own LLM for routing
    const decision = await serverLLM.decide(request);
    const tool = selectTool(decision);
    ```

    **Cost**: \$\$\$ (Server pays for LLM inference)
  </Tab>

  <Tab title="SuperModel Routing">
    ```typescript
    // 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)
  </Tab>
</Tabs>

**Tool Registry Configuration**:

```json
{
  "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.

<Steps>
  <Step title="Tool Execution">
    Selected tool processes the request and determines specific UI requirements
  </Step>

  <Step title="UI Generation via Sampling">
    Tool uses MCP sampling to generate AG-UI component code
  </Step>

  <Step title="Code Validation">
    Tool validates generated code for security and AG-UI compatibility
  </Step>

  <Step title="MCP-UI Packaging">
    Tool wraps generated UI as MCP-UI resource with proper MIME type
  </Step>
</Steps>

**UI Generation Sampling**:

```json
{
  "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:

<CardGroup cols={2}>
  <Card title="Deterministic Server Logic" icon="gear">
    All server operations are deterministic. The server executes decisions made by the client's LLM rather than making its own decisions.
  </Card>

  <Card title="Sampling-Only AI" icon="brain">
    Every point where AI reasoning is needed uses MCP sampling to delegate to the client's LLM.
  </Card>

  <Card title="Stateless Tools" icon="database">
    UI generation tools are stateless and only execute based on explicit instructions from sampling responses.
  </Card>

  <Card title="Context Passthrough" icon="arrow-right">
    Context flows through the system without server-side interpretation or modification.
  </Card>
</CardGroup>

## Framework Modularity

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

```typescript
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

<CardGroup cols={2}>
  <Card title="Zero-Inference Deep Dive" icon="dollar-sign" href="/concepts/zero-inference">
    Learn how SuperModel eliminates server inference costs completely.
  </Card>

  <Card title="Gateway Pattern" icon="route" href="/concepts/gateway-pattern">
    Understand intelligent routing and tool orchestration.
  </Card>

  <Card title="Hello World Example" icon="play" href="/examples/hello-world">
    See the architecture in action with a simple calculator example.
  </Card>

  <Card title="Multi-App Workflows" icon="workflow" href="/examples/multi-app-workflow">
    Explore complex user journeys across multiple UI apps.
  </Card>
</CardGroup>