Technology Overview & High-Level Tasks

This doc is the single reference for the stack and build checklist for AppiFire AI Chat. We implemented architecture Option A from Plan & architecture options (A, B, C): pgvector for vectors plus OpenRouter for embeddings and chat. Use that page for product scope, tiers, and how Options B/C differ.

---

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 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: prerequisites.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: shopify-app-skeleton-and-database.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: 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: 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.

Phase 4: Admin settings screen & storefront widget

Detailed plan: admin-settings-and-chat-widget.md

• Build admin settings UI (embedded app): widget title, welcome message, brand colour, bubble position; save to DB.
• Add reply delivery modes in Appearance: No Delay (default), Slow Typing like AI, and Delay Message with configurable seconds.
• 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 4.5: Knowledge bootstrap (first install)

Detailed plan: website-knowledge-from-web.md

• On first install only (afterAuth), trigger background website-knowledge bootstrap from https://{shop_domain}.
• Save fetched knowledge text to shop-level fields so the Knowledge screen opens prefilled.
• Auto-ingest fetched text into RAG (website source/document/chunks/embeddings) so chat can use baseline context without manual setup.
• Keep bootstrap non-blocking and silent on failure (install UX is never blocked).

Phase 4.6: First-install full RAG bootstrap + chat scope guardrails

• On first install only (afterAuth), run background “Update everything” equivalent sync for products, collections, inventory, and blogs with fullSync: true.
• Keep bootstrap fail-soft per resource: if one sync fails, continue install and let merchants retry from Data Sync.
• Add install-time sync summary logging (succeeded[], failed[]) for production troubleshooting.
• Tighten SYSTEM_PROMPT to store-only scope: refuse unrelated general-knowledge questions and avoid off-topic external links.

Phase 5: Billing & usage

Detailed plan: 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: 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	ShopifyAiChatbotPlanOptions.md
Shopify setup, CLI, extension, webhooks	SetupShopifyAndApp.md
Database schema (tables, indexes)	database-schema-for-rag.md
Product sync, chunking, embeddings	product-sync-and-ingestion.md
Knowledge bootstrap from shop domain	website-knowledge-from-web.md
RAG flow, chat API, cost tracking	rag-and-chat-api.md
Admin settings screen, chat widget	admin-settings-and-chat-widget.md
Billing, usage dashboard	billing-and-usage.md
Hosting, deployment, App Store submission	launch-and-publishing-guide.md
Roadmap, tech stack	my-rnd/readme.md

Once these tasks are done, you’ll have a working production stack aligned with architecture Option A (from the plan options doc): 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.