# shopify/shop-chat-agent architecture

> Architecture diagram of the GitHub repository shopify/shop-chat-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/shop-chat-agent
- Repository: https://github.com/shopify/shop-chat-agent

## Overview

##### Project type and purpose
- This is a full-stack Shopify template application that embeds an AI-powered chat widget on a storefront.
- The backend is a Remix server that acts as an MCP (Model Context Protocol) client and processes chat messages.
- The frontend is a Shopify theme extension (“chat-bubble”) that delivers the chat UI to end customers.

##### File structure
Top-level directories and files:
- app/
- auth.server.js, db.server.js, entry.server.jsx – core server setup
- mcp-client.js – initializes Shopify MCP tools (product search, cart actions, order lookup)
- routes/ – Remix route handlers for auth, webhooks, chat endpoints
- services/ – encapsulated logic for Claude integration, streaming responses, Shopify tool calls
- prompts/ – base prompts for LLM calls
- extensions/chat-bubble/
- assets/ (chat.js, chat.css) – static front-end code for the widget
- blocks/ – Liquid template to mount the widget in Shopify theme
- shopify.extension.toml – theme extension config
- prisma/ – SQLite schema and migrations for session storage
- shopify.app.toml, shopify.web.toml – Shopify app configs
- remix.config.js, vite.config.js – build and dev server configurations

##### README for additional insights
- Architecture summary confirms two main components: “Backend” (Remix app) and “Chat UI” (theme extension).
- Tech stack: Remix, Claude by Anthropic, @shopify/shopify-app-remix, SQLite via Prisma.
- Describes MCP tools integration, tunnels/local dev, and endpoints (/chat).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Storefront Layer
    subgraph "Storefront (Browser)"
        AssetChatJS["chat.js"]:::frontend
        AssetChatCSS["chat.css"]:::frontend
        LiquidBlock["blocks/chat-interface.liquid"]:::frontend
        ThemeExtension["Chat UI Theme Extension"]:::frontend
    end

    %% Backend Layer
    subgraph "Remix Backend"
        RemixCore["Remix Server Core"]:::backend
        subgraph "Authentication"
            OAuthLogic["OAuth2 Server Logic"]:::backend
        end
        ChatAPI["Remix /chat Route"]:::backend
        WebhookReceiver["Webhook Receiver"]:::backend
        MCPClient["MCP-Client Module"]:::backend
        subgraph "Services"
            ClaudeService["Claude LLM Service"]:::service
            ToolService["Shopify Tools Service"]:::service
            StreamingHandler["Streaming Response Handler"]:::service
            ConfigLoader["Configuration Loader"]:::service
        end
        Prompts["Base Prompts (prompts.json)"]:::backend
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        DBLayer["Prisma + SQLite"]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        ShopifyAPI["Shopify Admin API"]:::external
        ClaudeLLM["Claude LLM"]:::external
    end

    %% Connections
    LiquidBlock -->|Loads assets| AssetChatJS
    LiquidBlock -->|Loads assets| AssetChatCSS
    AssetChatJS -->|Embeds widget| ThemeExtension
    AssetChatCSS -->|Embeds widget| ThemeExtension

    ThemeExtension -->|POST /chat| ChatAPI
    ChatAPI -->|uses| ConfigLoader
    ChatAPI -->|fetch prompt| Prompts
    ChatAPI -->|calls| MCPClient
    MCPClient -->|calls| ToolService
    ToolService -->|requests| ShopifyAPI
    MCPClient -->|builds prompt| ClaudeService
    ClaudeService -->|streams| StreamingHandler
    StreamingHandler -->|streams response| ChatAPI
    ChatAPI -->|response| ThemeExtension

    ShopifyAPI -.->|webhook event| WebhookReceiver
    WebhookReceiver -->|updates sessions| DBLayer

    OAuthLogic -->|stores tokens| DBLayer
    OAuthLogic -->|calls| ShopifyAPI
    RemixCore --> OAuthLogic
    RemixCore --> ChatAPI
    RemixCore --> WebhookReceiver

    %% Click Events
    click AssetChatJS "https://github.com/shopify/shop-chat-agent/blob/main/extensions/chat-bubble/assets/chat.js"
    click AssetChatCSS "https://github.com/shopify/shop-chat-agent/blob/main/extensions/chat-bubble/assets/chat.css"
    click ThemeExtension "https://github.com/shopify/shop-chat-agent/tree/main/extensions/chat-bubble"
    click RemixCore "https://github.com/shopify/shop-chat-agent/tree/main/app/"
    click OAuthLogic "https://github.com/shopify/shop-chat-agent/blob/main/app/auth.server.js"
    click ChatAPI "https://github.com/shopify/shop-chat-agent/blob/main/app/routes/chat.jsx"
    click WebhookReceiver "https://github.com/shopify/shop-chat-agent/blob/main/app/routes/api.webhooks.jsx"
    click MCPClient "https://github.com/shopify/shop-chat-agent/blob/main/app/mcp-client.js"
    click ClaudeService "https://github.com/shopify/shop-chat-agent/blob/main/app/services/claude.server.js"
    click ToolService "https://github.com/shopify/shop-chat-agent/blob/main/app/services/tool.server.js"
    click StreamingHandler "https://github.com/shopify/shop-chat-agent/blob/main/app/services/streaming.server.js"
    click ConfigLoader "https://github.com/shopify/shop-chat-agent/blob/main/app/services/config.server.js"
    click Prompts "https://github.com/shopify/shop-chat-agent/blob/main/app/prompts/prompts.json"
    click DBLayer "https://github.com/shopify/shop-chat-agent/blob/main/prisma/schema.prisma"
    click RemixCore "https://github.com/shopify/shop-chat-agent/blob/main/app/routes.js"
    click BuildConfigs "https://github.com/shopify/shop-chat-agent/blob/main/remix.config.js"

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:2px
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef service fill:#87CEFA,stroke:#333,stroke-width:2px
    classDef database fill:#0000CD,stroke:#333,stroke-width:2px
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px
```
