botino/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Development
npm run dev          # Start with nodemon auto-reload
npm start            # Production start

# Testing
npm test             # Run all tests once (vitest run)
npm run test:watch   # Watch mode
npm run test:coverage

# Run a single test file
npx vitest run src/modules/3-turn-engine/orderModel.test.js

# Database migrations (requires DATABASE_URL in .env)
npm run migrate:up
npm run migrate:down
npm run migrate:redo
npm run migrate:status
npm run seed         # Seed a tenant via scripts/seed-tenant.mjs

No lint command is configured.

Product goal

The bot must be conversational and intelligent, not a menu-driven flow. Customers reach out via WhatsApp with intent to buy — the bot's job is to:

1. Engage in conversation — answer questions about products, prices, availability/stock; recommend; clarify.
2. Take orders — build a cart through natural dialogue (multi-product turns, quantities, units).
3. Collect delivery data — address, delivery vs pickup, payment method.
4. Operate within store rules — delivery zones, days/hours, pickup windows. These config tables (delivery_zones, store schedule in tenant_settings) will be populated later; the bot has to read and respect them when present.

Repetitive, hardcoded responses are a known quality problem and the focus of the active improvement plan (see ~/.claude/plans/ok-creo-que-tiene-humming-sutton.md). The system is not yet in production — refactors that change behavior are acceptable.

Architecture

This is a mono-tenant WhatsApp e-commerce chatbot powered by Express.js. The store operator hooks the bot to a single WooCommerce shop; customers interact via WhatsApp to browse products, build carts, and place orders.

The DB schema retains tenant_id columns (it was originally multi-tenant) but the app boots with a single tenant resolved at startup. The single id is exposed via src/modules/shared/tenant.js (getTenantId()); webhook handlers and intake routes read from there instead of looking up tenants per-request.

Request flow

WhatsApp → Evolution API webhook → /webhook/evolution (or /sim/send)
                                         ↓
                              1-intake: route & normalize message
                                         ↓
                              2-identity/pipeline.processMessage (idempotency, history, side effects)
                                         ↓
                              3-turn-engine/agent: tool-calling LLM loop
                                         ↓
                              Response persisted to DB + sent back via Evolution API

Turn engine: tool-calling agent (DeepSeek)

src/modules/3-turn-engine/agent/ es el único motor. Cada turno arma un WorkingMemory (cart, pending, last_shown_options, store, history truncado, customer_profile, preparsed quantity) y se lo pasa al LLM como user message. El LLM decide qué tools llamar:

• search_catalog, add_to_cart, set_quantity, select_candidate, remove_from_cart
• set_shipping, set_address, confirm_order
• pause, escalate_to_human
• say (último siempre — es el reply al usuario)

El system prompt es estático (en agent/systemPrompt.js como SYSTEM_PROMPT const) para que DeepSeek lo cachée prefix-cache automáticamente. Cache hit ratio típico ≥70% después de 2 turnos. El parser de cantidades (agent/quantityParser.js) preprocesa el texto y se pasa como working_memory.preparsed (fracciones, "media docena", "cuarto kilo", etc.).

La FSM (fsm.js) sigue siendo guardrail: estados IDLE / CART / SHIPPING / PAUSED / AWAITING_HUMAN con transiciones validadas. PAUSED tiene TTL 7d (cart preservado para "después te digo").

Module structure (numbered layers)

• src/modules/0-UI/ — Admin dashboard: REST controllers para products, conversations, settings, takeovers, recommendations, aliases.

• src/modules/1-intake/ — Message ingestion. Routes: /simulator (dev UI), /webhook/evolution (WhatsApp).

• src/modules/2-identity/ — User mapping (WhatsApp ↔ WooCommerce customer), encrypted WooCommerce credentials, pipeline orchestrator.

• src/modules/3-turn-engine/ — Agente tool-calling (agent/), FSM (fsm.js), order model (orderModel.js), catalog retrieval (catalogRetrieval.js), store context (storeContext.js).

• src/modules/4-woo-orders/ — WooCommerce order sync (lectura). El bot crea orders nuevas vía wooOrders.createOrder desde pipeline.js cuando emite la action create_order.

• src/modules/shared/ — DB pool, SSE, WooSnapshot, tenant resolver (getTenantId()), debug.

Key integrations

System	Purpose	Config
LLM (DeepSeek)	Agente tool-calling — único motor	OPENAI_API_KEY, OPENAI_BASE_URL=https://api.deepseek.com/v1, OPENAI_MODEL=deepseek-chat
Evolution API	WhatsApp send/receive	EVOLUTION_*, EVOLUTION_SEND_ENABLED
WooCommerce REST API	Products, orders, customers	WOO_BASE_URL, WOO_CONSUMER_KEY, WOO_CONSUMER_SECRET
PostgreSQL	Primary database	DATABASE_URL

Database

Migrations live in db/migrations/ as timestamped SQL files managed by dbmate. Key tables:

• tenants, tenant_config, tenant_settings, tenant_ecommerce_config, tenant_channels
• wa_identity_map — WhatsApp ↔ WooCommerce customer mapping
• wa_conversation_state — FSM state + context (cart, pending, last_shown_options, paused_until) en JSONB
• wa_messages — Message history (idempotencia por message_id)
• woo_products_snapshot — Cached product catalog (con índices pg_trgm en aliases)
• product_aliases, alias_product_mappings — fuzzy alias resolution
• woo_orders_cache + woo_order_items — orders sync para customer_profile / stats
• human_takeovers, audit_log, conversation_runs

Feature flags (env vars)

• AGENT_MAX_TOOL_CALLS=10 — cap de tool calls por turno
• AGENT_TURN_TIMEOUT_MS=25000 — timeout total del turno
• EVOLUTION_SEND_ENABLED=1 — enviar a WhatsApp real (off en dev)
• DEBUG_PERF, DEBUG_WOO_HTTP, DEBUG_LLM, DEBUG_EVOLUTION — debug logs granular

Métricas

• GET /api/metrics/agent — turns, avg tool calls, fallback rate, escalations, cache_hit_ratio (prompt caching de DeepSeek)

Local development

Copy env.example to .env and fill in values. Use docker-compose.override.yaml for local overrides. Run docker compose up to start app + Postgres + Redis. The Dockerfile runs migrations automatically on startup (migrate:up && seed && start).

Test files use Vitest with globals: true — no need to import describe, it, expect.