Option A: Technology Overview & High-Level Tasks

This document is the single reference for what you’re using and what you need to do when building AppiFire AI Chat with Option A (pgvector + OpenRouter for embeddings and chat). For full plan and pricing, see Shopify-AI-Chatbot-Plan-Options.md.

1. Technology Overview

High-level picture

┌─────────────────────────────────────────────────────────────────────────────┐
│  SHOPIFY                                                                     │
│  ┌──────────────────────┐    ┌───────────────────────────────────────────┐  │
│  │  Admin (embedded app)│    │  Storefront (Theme App Extension)         │  │
│  │  - Config screen     │    │  - Chat widget (React / Liquid + JS)       │  │
│  │  - Settings, usage   │    │  - Calls your Backend API for chat        │  │
│  └──────────┬───────────┘    └───────────────────┬─────────────────────┘  │
└─────────────┼──────────────────────────────────────┼────────────────────────┘
              │                                      │
              │  OAuth, webhooks, product sync       │  POST /chat (message)
              ▼                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  YOUR BACKEND (Node/Remix or FastAPI)                                         │
│  - Shopify OAuth & session                                                    │
│  - Product sync (Admin API) + webhooks (products/create, update, delete)     │
│  - Chunking + OpenRouter embeddings → pgvector                                │
│  - RAG: embed query → vector search → OpenRouter chat → return reply          │
│  - Usage logging (shop_id, cost, tokens) for per-client attribution          │
│  - Billing: reply count, Shopify Billing API                                 │
└─────────────┬─────────────────────────────────────┬─────────────────────────┘
              │                                     │
              ▼                                     ▼
┌─────────────────────────────┐    ┌──────────────────────────────────────────┐
│  POSTGRES + PGVECTOR         │    │  OPENROUTER.AI                            │
│  - shops, products,         │    │  - Embeddings API (e.g. text-embedding-   │
│    product_variants          │    │    3-small) for ingest + query embedding  │
│  - knowledge_sources,       │    │  - Chat API (e.g. grok/mini, Claude, GPT)  │
│    knowledge_documents,      │    │  - Single bill; log cost per shop_id      │
│    knowledge_chunks          │    │    in your DB for attribution            │
│  - embeddings (vector 1536)  │    └──────────────────────────────────────────┘
│  - chat_sessions,            │
│    chat_messages,            │
│    retrieved_chunks          │
│  - usage / openrouter_calls  │
└─────────────────────────────┘

Technologies you will use

Layer	Technology	Purpose
Shopify app	Shopify CLI, Remix (or Node), App Bridge	Create app, embedded admin UI, OAuth, webhooks
Storefront chat	Theme App Extension (Liquid + JS, or React loaded via extension)	Chat widget on merchant store; calls your backend
Backend API	Node.js (Remix) or Python (FastAPI)	App server: auth, product sync, RAG orchestration, chat endpoint
Backend database	PostgreSQL + pgvector	Shops, products, chunks, embeddings (vectors), chat history, usage
Embeddings	OpenRouter.ai (embeddings API)	Turn text into vectors (ingest + query); e.g. `openai/text-embedding-3-small`
Chat LLM	OpenRouter.ai (chat API)	Generate replies; free/cheap model for free tier, better model for paid
Hosting (backend + DB)	Your choice: VPS (e.g. DigitalOcean, Hetzner), or managed (e.g. Railway, Render, Fly.io; Postgres with pgvector)	Run backend and Postgres; prefer DB on separate instance from app

2. What You Have to Set Up

Accounts & access

Item	What to do
Shopify Partner	Create account at partners.shopify.com; type Developer, purpose “Build apps for the App Store”.
Development store(s)	Create at least one dev store in Partner Dashboard (Stores → Add store → Development store) to test the app.
OpenRouter.ai	Sign up at openrouter.ai; get API key; add credits. Use same key for embeddings and chat so all AI billing is there.
Backend hosting	Choose provider (e.g. Railway, Render, Fly.io, DigitalOcean); create project and (if needed) database.

Infra & services

Item	What to do
PostgreSQL with pgvector	Provision Postgres (self-hosted or managed, e.g. Supabase, Neon, AWS RDS, Railway). Enable pgvector extension. Create DB and run migrations for schema from Option-A-Phase-01-Design database schema for RAG.md.
Backend app	Create app with `shopify app init` (choose Remix or React Router when prompted). Backend runs on your host; needs env: `SHOPIFY_*`, `DATABASE_URL`, `OPENROUTER_API_KEY`, app URL for OAuth.
Shopify app config	In Partner Dashboard and `shopify.app.toml`: set app URL (your backend), redirect URLs, scopes (`read_products`, `read_inventory`, `read_content`, `read_themes`), and webhook subscriptions (products/create, update, delete; app/uninstalled).
Theme App Extension	Generate extension (`shopify app generate extension` → Theme app extension). Add chat block that loads your widget and points to your backend API.

Subdomains (appifire.com)

Subdomain	Purpose
appifire.com	Marketing website (landing, docs, signup).
ai-chat.appifire.com	This app (AppiFire AI Chat). Set App URL in Shopify to `https://ai-chat.appifire.com`.
<app-name>.appifire.com	Future apps: one subdomain per app (e.g. `xyz.appifire.com`), no path or folder routing.
app.appifire.com (optional)	Use later if you add a standalone merchant dashboard or login outside Shopify.

Recommendation: use one subdomain per app (e.g. ai-chat.appifire.com) so each app is a separate deployment at root / with no path prefix or shared routing.

Environment / secrets (backend)

SHOPIFY_API_KEY, SHOPIFY_API_SECRET (from Partner Dashboard).
DATABASE_URL (Postgres connection string).
OPENROUTER_API_KEY.
App URL and redirect URLs for OAuth: https://ai-chat.appifire.com (this app’s subdomain; marketing site is appifire.com).

3. High-Level Task List

Use this as a checklist; order is roughly sequential. Details live in Setup Shopify & App and Design database schema for RAG.

Phase 0: Prerequisites

Detailed plan: Option-A-Phase-0.md

Create Shopify Partner account and development store.
Install Node.js 18+ and Shopify CLI; run shopify login.
Sign up for OpenRouter.ai; get API key and add credits.
Choose hosting for backend + Postgres; provision Postgres with pgvector enabled.

Phase 1: Shopify app skeleton & database

Detailed plan: Option-A-Phase-1.md

Create Shopify app (shopify app init — choose Remix or React Router template, public app).
Configure shopify.app.toml (scopes, app URL when deployed).
Create database and run migrations (tables: shops, products, product_variants, knowledge_sources, knowledge_documents, knowledge_chunks, embeddings, chat_sessions, chat_messages, retrieved_chunks, optional ingestion_jobs and usage/openrouter_calls).
Implement OAuth install/callback and session storage (e.g. Prisma/session table or Shopify’s session storage).
Register webhooks: products/create, products/update, products/delete, app/uninstalled.

Phase 2: Product sync & ingestion

Detailed plan: Option-A-Phase-2-Product-Sync-and-Ingestion.md

Implement product sync: on install and via webhooks, fetch products (Admin API) and write to products (and product_variants).
Build chunking: turn product (and optional FAQ/policy) content into knowledge_chunks (e.g. 300–700 tokens per chunk).
Integrate OpenRouter embeddings API: for each chunk, call OpenRouter → get vector → store in embeddings with knowledge_chunks.id and shop_id; create/use ivfflat or HNSW index.
Ensure tenant isolation: all reads/writes filter by shop_id; re-embed only affected chunks when a product updates.

Phase 3: RAG & chat API

Detailed plan: Option-A-Phase-3-RAG-and-Chat-API.md

Implement chat endpoint (e.g. POST /api/chat): accept shop identifier + user message; validate session/store.
RAG flow: embed user message via OpenRouter embeddings → vector search in pgvector (filter by shop_id) → get top-k chunks → build prompt with context → call OpenRouter chat API → return reply.
Log each request: store (shop_id, cost, tokens) from OpenRouter response (e.g. in openrouter_calls or usage table) for per-client attribution.
Enforce reply-based limits: check reply count for shop/plan before generating; increment reply count after successful reply.

Detailed plan: Option-A-Phase-4-Admin-Settings-and-Chat-Widget.md

Build admin settings UI (embedded app): widget title, welcome message, brand colour, bubble position; save to DB.
Create Theme App Extension: add block (e.g. chat widget) that loads your frontend (React or vanilla JS) and passes shop/visitor context.
Chat widget: call your backend POST /api/chat with message; display streamed or single reply; show “Replies used / remaining” if you expose it from backend.

Phase 5: Billing & usage

Detailed plan: Option-A-Phase-5-Billing-and-Usage.md

Integrate Shopify Billing API: one subscription tier $10/mo ($10 credits ≈ 500 messages); optional add-on credit packs or usage-based overage.
Enforce limits: free = 50 replies/mo; paid = 500 + add-on credits; block or upsell when over limit.
Show usage in admin: replies used this month, credits remaining, subscribe / buy add-on.

Phase 6: Launch & publishing

Detailed plan: Option-A-Phase-6-Launch-and-Publishing-Guide.md

Deploy backend to Railway/Render at https://ai-chat.appifire.com; custom domain SSL active.
Run shopify app deploy to push extension and toml; create active app version in dev.shopify.com.
Complete production checklist: GDPR webhooks, privacy policy URL, listing assets, test instructions for reviewers.
Submit for review via Partner Dashboard → Distribution → Shopify App Store.

4. Doc References

Need	Document
Plan A/B/C, pricing, API key, infra	Shopify-AI-Chatbot-Plan-Options.md
Shopify setup, CLI, extension, webhooks	my-rnd/Setup Shopify & App.md
Database schema (tables, indexes)	Option-A-Phase-01-Design database schema for RAG.md
Product sync, chunking, embeddings	Option-A-Phase-2-Product-Sync-and-Ingestion.md
RAG flow, chat API, cost tracking	Option-A-Phase-3-RAG-and-Chat-API.md
Admin settings screen, chat widget	Option-A-Phase-4-Admin-Settings-and-Chat-Widget.md
Billing, usage dashboard	Option-A-Phase-5-Billing-and-Usage.md
Hosting, deployment, App Store submission	Option-A-Phase-6-Launch-and-Publishing-Guide.md
Roadmap, tech stack	my-rnd/readme.md

Once these tasks are done, you’ll have a working Option A stack: Shopify app + admin config, storefront chat, backend with pgvector and OpenRouter (embeddings + chat), and billing based on reply count with full cost visibility per store.