Shopify App Factory

Multi-tenant Micro-SaaS factory — three AI-powered Shopify apps on a single FastAPI + PostgreSQL backend.

Apps

App	Trigger	What it does
Smart Operations Tagging	orders/create webhook	Reads customer notes, item details, risk factors → auto-applies operational tags (Rush, Fragile, Gift, etc.)
Zero-UI Synonym Injector	Cron / failed searches	Detects "no results" searches, generates synonyms via AI → feeds into Shopify Search & Discovery
SEO Meta-Data Engine	products/create webhook	Replaces messy supplier text with optimized title tags, meta descriptions, alt text, keywords

All three are zero-UI — merchants install via OAuth and the apps run silently in the background.

Quick Start

# Windows
.\venv\Scripts\python.exe main.py                       # App server (:8000)
.\venv\Scripts\python.exe observability/main.py          # Dashboard (:9000)
.\venv\Scripts\python.exe -m celery -A tasks.celery_app worker --pool=solo --loglevel=info  # Celery worker
.\venv\Scripts\python.exe scripts\simulate_webhooks.py   # Local simulation

# Mac / Linux
venv/bin/python main.py
venv/bin/python -m celery -A tasks.celery_app worker --pool=solo --loglevel=info

Environment

Copy .env.example to .env and fill in:

• DATABASE_URL — PostgreSQL connection (dev: port 5433, prod: Neon pooled)
• SHOPIFY_API_KEY / SHOPIFY_CLIENT_SECRET — Shopify Partner app credentials
• LLM_API_KEY — sk-... key for the LLM API (default: api.deepseek.com/v1)

All settings have defaults in config/settings.py.

Architecture

webhooks (Shopify)
    │
    ▼
main.py (FastAPI :8000) ── HMAC validation ── billing gate
    │
    ├── routes/          OAuth install, billing upgrade/confirm, admin stats
    ├── webhooks/        order, product, search, subscription handlers
    ├── services/        ShopifyAdapter, LLMAgent, RAG storage
    ├── middleware/       subscription gating (trial → paid)
    ├── tasks/           Celery worker (offloads LLM calls from webhook thread)
    │
    ▼
PostgreSQL (Neon serverless) + pgvector/HALFVEC(3072) RAG store

Webhook handlers return 200 OK within 4s (Shopify's 5s timeout) by dispatching heavy inference to Celery workers.

Project Layout

├── main.py              Entry point, 5 routers, uvicorn :8000
├── config/settings.py   Env vars + fallbacks
├── database/            SQLAlchemy models (Merchant, Subscription, UsageLog, TenantKnowledgeEmbedding)
├── routes/              OAuth install (auth.py), billing (billing.py)
├── services/            ShopifyAdapter, LLMAgent, RAG storage, webhook registration
├── tasks/               Celery app + worker tasks
├── middleware/           Billing subscription gate
├── utils/               HMAC validation (FastAPI dependency)
├── webhooks/            Order, search, product, subscription, GDPR handlers
├── observability/       Security breach dashboard (:9000)
├── scripts/             Test suite (Phases 1-5), simulation, RAG tests
├── tests/               Unit tests (pytest)
├── docs/                Deployment, costs, privacy, support
└── plans/               Launch roadmap

Commands

# Tests
.\venv\Scripts\python.exe -m pytest tests/ -v

# Full test suite
.\venv\Scripts\python.exe scripts\test_all.py
.\venv\Scripts\python.exe scripts\test_security_resilience.py
.\venv\Scripts\python.exe scripts\test_rag.py

# Ngrok tunnel (for local Shopify OAuth)
ngrok http 8000

Key Design Decisions

• Gross margin target: 95%+ — DeepSeek inference costs ~$0.06/customer/month
• Multi-tenancy: Composite unique (shop_domain, app_identifier) — one shop can install multiple apps
• HMAC validation: hex digest (not base64), centralized in utils/shopify_security.py as a FastAPI dependency
• Billing: 14-day trial → 50 ops/month freemium hook → $9.99/mo flat rate via Shopify's appSubscriptionCreate mutation
• Embeddings: HALFVEC(3072) single column, provider-agnostic; production uses OpenAI text-embedding-3-large
• LLM timeouts: 30s for tagger/synonyms, 60s for SEO (higher output tokens)

Docs

Document	Contents
docs/deployment.md	Infra setup, Neon provisioning, CI/CD, rate limiting, health checks
docs/production-costs.md	Full opex breakdown, unit economics, scaling triggers, Hetzner vs Render
docs/privacy-policy.md	Data collection, retention, GDPR compliance, DeepSeek disclosure
docs/support.md	Merchant guides, FAQ, troubleshooting per app, billing
docs/platform-expansion.md	Multi-platform roadmap: WooCommerce, Amazon, TikTok Shop, BigCommerce, Adobe Commerce
plans/launch-roadmap.md	7-phase launch plan, dependency graph, checklist
assets/listing-copy.md	App Store titles, subtitles, descriptions, key features

Production

Recommended infra: Hetzner CX22 VPS ($4/mo) running app + worker + Redis via Docker Compose, Neon free-tier Postgres. Break-even at 1 customer. Full details in docs/production-costs.md.