ShopMate
Autonomous AI Operations Employee for Shopify Store Owners (Internal Operations & Support)
Private Repository Notice
Private Client & Internal Operations Repository. Demonstration architecture and live store deployment available upon request.
Free & Open Architecture Alternative To:
💰 Value & Cost Savings Comparison
Traditional Industry Solution
Gorgias / Intercom Shopify Helpdesk per-ticket fees
$300 - $900 / month
This Project (By Owais Abdullah)
Internal Digital Employee (Fixed Model Compute)
Eliminates recurring per-ticket and per-seat support fees
🎯 Pain Points Solved
Why this project was built and the operational friction it eliminates:
The Problem
Shopify store owners spend hours every day answering repetitive 'Where is my order?' (WISMO) questions instead of focusing on growth and sourcing.
The Solution
ShopMate securely connects to Shopify APIs to verify order numbers and emails, fetching live fulfillment statuses and tracking links in seconds.
The Problem
South Asian and diaspora e-commerce stores lose sales when support chatbots fail to understand mixed languages like Roman Urdu and Urdu phrasing.
The Solution
Engineered with trilingual language comprehension (English, Urdu, Roman Urdu) to converse naturally with local and international shoppers.
The Problem
Generic support bots improvise and hallucinate inventory numbers, discounts, or return policies.
The Solution
Enforces a strict 10-step loop: classification into explicit markdown skills, ground verification against live catalog/FAQ, and zero out-of-scope improvisation.
The Problem
Store owners lack visibility into after-hours customer inquiries, lost sales, and complaints.
The Solution
Generates an automated daily digest in the owner's terminal summarizing inquiries handled, captured leads, and issues requiring personal escalation.
⚡ Core Capabilities & Architecture
ShopMate operates on the Agent Factory architecture: an agent brain executing portable markdown skills backed by Neon Postgres memory (pgvector embeddings for FAQ/policy RAG) and Shopify Storefront/Admin MCP tools. Messages pass through a mandatory 10-step loop: Context Loading -> Skill Classification -> Plan Cap Verification -> Role Authentication -> Catalog Grounding -> Approval Check -> Action Execution -> Ledger Recording -> Redacted Telemetry -> Grounded Response.
- ✔Store Owner Operations Focus: Built exclusively for store owners and internal teams to manage customer service, lead capture, and daily summaries
- ✔Trilingual Shopper Support: Smoothly answers product queries and policies in English, Urdu, and Roman Urdu
- ✔Grounded Order Tracking: Verifies order number and email against live Shopify Storefront and Admin APIs before revealing fulfillment details
- ✔Lead Capture Engine: Automatically records buying intent, wholesale/bulk inquiries, and unanswered questions with timestamps
- ✔Runtime Agnostic Brain: Pluggable agent runtime supporting OpenCode, Qwen Code, Claude Code, and Command Code via LiteLLM
- ✔Zero-Improvisation Safeguard: Escalate angry customers, legal threats, or off-policy requests to the store owner rather than hallucinating
🛠️ How to Setup & Run Locally
Quick-start guide to clone, configure, and execute this project in your own environment:
Prerequisites
- Python 3.11+ with uv package manager
- Shopify Custom App Access Token (read_products, read_orders, read_customers)
- Shopify Storefront API Access Token
- Neon PostgreSQL database with pgvector
- OpenRouter API Key (for DeepSeek routine models) or Gemini API Key
Key Environment Variables (.env)
| Variable | Description | Example / Format |
|---|---|---|
| EDITION | Deployment edition: community (read-only) or hosted (write/actions) | community |
| RUNTIME | Agent execution runtime | opencode |
| SHOPIFY_STORE | Your Shopify store domain | yourstore.myshopify.com |
| SHOPIFY_ADMIN_TOKEN | Shopify Custom App Admin API token | shpat_... |
| SHOPIFY_STOREFRONT_TOKEN | Shopify Storefront API access token | sf_tok_... |
| NEON_DATABASE_URL | Neon PostgreSQL connection string for agent memory | postgres://... |
| OPENROUTER_API_KEY | OpenRouter key for DeepSeek V4 Flash default model | sk-or-v1-... |
| GEMINI_API_KEY | Direct Gemini API key for fallback routing | AIzaSy... |
| EMBEDDINGS | Vector embeddings model provider | openrouter:openai/text-embedding-3-small |
Execution Steps
1.Request Repository Access or Review Community Specs
ShopMate core is an internal proprietary project. Authorized team members clone from the private remote; open community guidelines are documented below.
2.Install dependencies using uv
uv syncProvisions Python virtual environment from pyproject.toml.
3.Configure environment variables
cp .env.example .envSet your SHOPIFY_STORE, SHOPIFY_ADMIN_TOKEN, SHOPIFY_STOREFRONT_TOKEN, and NEON_DATABASE_URL.
4.Verify credentials and connections
uv run shopmate doctorLive-checks database connectivity, embeddings provider, and model alias routing.
5.Initialize database and start terminal employee
uv run shopmate init && uv run shopmate serveCreates memory tables and begins serving customer inquiries and generating daily operations digests.
🗺️ Project Roadmap & Planned Improvements
Current release progress and planned future enhancements:
Trilingual Customer Ingestion
Fluent understanding of English, Urdu, and Roman Urdu customer inquiries grounded in live catalog data.
WhatsApp Storefront Dispatcher
Connect ShopMate directly to WhatsApp Business API for instant conversational order lookups.
Autonomous Theme Editor with Visual Staging
Hosted capability allowing store owners to request banner changes and promotion launches via staged previews.
License, Fair Use & Attribution Terms
Proprietary / Private Internal Core (Community Specs Available)
ShopMate core and hosted editions are proprietary internal software developed for managed e-commerce clients. Source code is maintained in a private repository; open community guidelines and connection specs are documented for portfolio review.