---
title: FlexiGo Support Bot
emoji: 💬
colorFrom: red
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# Shopify Support Chatbot

Chatbot de soporte embebible para tiendas **Shopify**. Responde dudas de
**información** (catálogo en vivo + base de conocimiento de PDFs/URLs) y de
**pedidos** (estado y nº de seguimiento, con verificación de identidad), en el
**idioma del cliente**. Cerebro LLM **gratis** (Groq con failover a Cloudflare
Workers AI), embeddings **locales**. Pensado para una tienda y reutilizable.

> Diseño: [`docs/superpowers/specs/2026-06-09-shopify-support-chatbot-design.md`](docs/superpowers/specs/2026-06-09-shopify-support-chatbot-design.md)
> Plan: [`docs/superpowers/plans/2026-06-09-shopify-support-chatbot.md`](docs/superpowers/plans/2026-06-09-shopify-support-chatbot.md)

## Arquitectura

```
Widget (Theme App Extension)  ──/apps/chat (App Proxy, sin CORS, HMAC)──►  FastAPI
                                                                            │
   ┌────────────────────────────────────────────────────────────────────┐ │
   │ Orquestador (tool-calling)                                           │ │
   │   • search_knowledge  → RAG (pgvector + embeddings locales)          │ │
   │   • search_products   → Shopify GraphQL Admin API                    │ │
   │   • lookup_order      → Shopify GraphQL + verificación de identidad  │ │
   │   • escalate_to_human → email al equipo                              │ │
   │ LLM: Groq (primario) → Cloudflare Workers AI (failover)              │ │
   └────────────────────────────────────────────────────────────────────┘ │
                                  Postgres + pgvector ◄──────────────────────┘
```

## Stack
Python 3.12 · FastAPI · SQLAlchemy 2 (async) · Postgres + pgvector · Alembic ·
fastembed (ONNX, multilingüe) · httpx · pytest. Gestor: **uv**.

## Desarrollo local

```bash
uv sync                      # crea el venv (Python 3.12) e instala dependencias
cp .env.example .env         # rellena las claves (ver abajo)
uv run uvicorn app.main:app --reload
# Tests:
uv run pytest                # suite completa (incluye el test lento del embedder)
uv run pytest -m "not slow"  # rápido (sin cargar el modelo de embeddings)
uv run ruff check .          # lint
```
Sin Postgres local puedes usar sqlite para una prueba rápida:
`DATABASE_URL=sqlite+aiosqlite:///./dev.db` (pgvector solo en Postgres; en sqlite
la búsqueda RAG usa coseno en Python).

## Claves LLM (gratis)

- **Groq** (primario): crea una API key en <https://console.groq.com> (gratis, sin
  tarjeta). Uso comercial permitido y **no entrena con tus datos**. → `GROQ_API_KEY`.
- **Cloudflare Workers AI** (failover): Account ID + API token de Workers AI.
  Gratis (10.000 neuronas/día), **no entrena con tus datos**. →
  `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`.

Mismos modelos Llama 3.3 70B / 3.1 8B en ambos, así que el failover es transparente.
**Camino de upgrade** si la tienda crece: Groq de pago, o Cloudflare con facturación,
o Gemini de pago — basta cambiar variables de entorno (`LLM_PROVIDER_ORDER` + claves).

Embeddings: modelo multilingüe local (`fastembed`), 0 €, sin enviar datos a terceros.

## 🚀 Despliegue (multi-tenant: el cliente no toca nada)

**Modelo:** NOSOTROS alojamos **un solo backend** que sirve a **todos los clientes**
(cada uno es un *tenant*). El cliente solo recibe **una línea** para pegar (o se la
pegamos). Cero infraestructura, cero claves, cero Railway para el cliente.

### Una vez (nosotros) — desplegar el backend
1. Desplegar este repo en Railway (usa [`railway.json`](railway.json): migraciones +
   uvicorn + healthcheck `/healthz`, automático).
2. Volumen en `/app/data` (SQLite + caché del modelo).
3. Variables: `GROQ_API_KEY` (nuestra), `ADMIN_TOKEN` (nuestra), `SECRET_KEY` (cifra
   los secretos de los tenants), `DATABASE_URL=sqlite+aiosqlite:////app/data/bot.db`.
   (Opcional `CLOUDFLARE_*` para el failover.)

### Por cada cliente (alta de 5 min, en `/admin/`)
1. Entrar en `https://NUESTRO_BACKEND/admin/` con el `ADMIN_TOKEN`.
2. **Crear la tienda** (slug, p.ej. `toorx`), poner nombre/color/bienvenida.
3. Subir sus **PDFs/URLs** (base de conocimiento, aislada por tenant).
4. (Opcional, para pedidos) pegar las credenciales de su **custom app de Shopify**
   (`shop`, `client_id`, `client_secret` — se guarda **cifrado**). Sin esto = bot solo-info.
5. Copiar la **línea de incrustación** que muestra el panel:

```html
<script src="https://NUESTRO_BACKEND/widget.js?t=toorx" defer></script>
```

### El cliente — pega 1 línea
En su tema de Shopify (**Online Store → Themes → Edit code → `theme.liquid`**, antes
de `</body>`), pega esa línea. **Fin.** El widget se sirve solo, detecta su backend y
su tienda por el `?t=`, lee su marca de `/widget-config` y habla con `/chat` (CORS).

> Aislamiento: la base de conocimiento, sesiones y pedidos de cada tenant están
> separados por `tenant_id`; una tienda nunca ve los datos de otra.

### (Opcional) Modo seguro con App Proxy
Si un cliente quiere firmas HMAC + `logged_in_customer_id` en vez del `<script>`:
desplegar `extension/` con `shopify app deploy`, configurar el App Proxy
(`subpath=chat`, `prefix=apps`, URL → `/apps/chat`) y activar el bloque en *App embeds*.
`/apps/chat` resuelve el tenant por el `shop` firmado.

### (Opcional) Postgres + pgvector a escala
Cambia `DATABASE_URL` a Postgres; la migración crea la extensión `vector` y usa
búsqueda vectorial nativa. (En SQLite la búsqueda RAG usa coseno en Python.)

## Privacidad / GDPR
- LLMs sin entrenamiento con datos (Groq + Cloudflare) → seguro para datos de pedidos.
- Verificación por niveles: email + nº de pedido; solo se revela estado de envío +
  seguimiento (nunca dirección completa ni pago). Errores genéricos + bloqueo por
  intentos.
- Retención: las sesiones/mensajes se purgan automáticamente a los
  `SESSION_RETENTION_DAYS` días.