Skip to main content

Architecture Overview

The chat commerce system has three main components that work together to enable conversational shopping.

System Diagram​

┌──────────────────────────────────────────────────────┐
│                    Customer's Phone                   │
│                                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │           iOS / Android App                      │ │
│  │                                                  │ │
│  │  ┌──────────┐  ┌────────────┐  ┌──────────────┐│ │
│  │  │ Chat UI  │  │ MCP Server │  │  App Services ││ │
│  │  │(SwiftUI/ │──│ (Tool      │──│  (Hybris API, ││ │
│  │  │ Compose) │  │  Execution)│  │   Cart, Auth) ││ │
│  │  └────┬─────┘  └────────────┘  └──────────────┘│ │
│  │       │                                         │ │
│  └───────┼─────────────────────────────────────────┘ │
│          │                                           │
└──────────┼───────────────────────────────────────────┘
           │ HTTPS
           ▼
┌──────────────────────────────────┐
│         LLM Proxy                │
│      (Cloud Run, Node.js)        │
│                                  │
│  ┌────────────┐ ┌──────────────┐│
│  │ Base System │ │   Provider   ││
│  │ Prompt      │ │   Router     ││
│  │ + Security  │ │ (Claude,     ││
│  │ Guardrails  │ │  Gemini,     ││
│  └────────────┘ │  Bedrock)    ││
│                  └──────┬───────┘│
│                         │        │
└─────────────────────────┼────────┘
                          │ API calls
                          ▼
               ┌────────────────────┐
               │   LLM Providers    │
               │ (Claude, Gemini,   │
               │  Bedrock)          │
               └────────────────────┘

Components​

1. Mobile App (iOS / Android)​

The customer-facing app contains:

  • Chat UI — The conversational interface (SwiftUI on iOS, Jetpack Compose on Android). Accessed via a floating action button on the home screen.
  • MCP Server — Runs locally on the device. Receives tool calls from the LLM and executes them against the app's existing services. No network latency for tool execution.
  • App Services — Existing Hybris API client, cart manager, auth layer, navigation — the MCP server delegates to these.

2. LLM Proxy (Backend)​

A Node.js Express service deployed on Google Cloud Run (Johannesburg region):

  • Prompt Management — Owns the base system prompt with security guardrails. Clients can extend but not override it.
  • Provider Routing — Supports Claude (Anthropic), Gemini (Google), and Bedrock (AWS). Translates MCP tool definitions into each provider's native format.
  • Session Logging — Logs every conversation turn for debugging and auditing.
  • Rate Limiting — Protects against abuse.

3. LLM Providers​

The actual AI models that understand the customer's intent and decide which tools to call. The proxy abstracts provider differences so the app doesn't need to know which model is being used.

Key Design Decisions​

Tools execute locally on the device​

MCP tools run inside the app, not on a server. This means:

  • No additional network latency for tool execution
  • Access to device state (auth tokens, cart, location) without sending it to a server
  • Offline-capable for cached data (though the LLM itself requires network)

Three-layer prompt architecture​

The system prompt is composed of three layers (see Prompt Architecture):

  1. Base prompt (server) — Identity, security guardrails, tone
  2. Client extension (app) — UI rules, workflow instructions, division context
  3. Session context (app) — Current cart, recent orders, auth status

Tool definitions are client-driven​

The app sends its available tools with each request. This means:

  • Different platforms can have different tool sets
  • Tools can be added/removed without changing the proxy
  • Feature flags can control tool availability