JUNOHUB-test/docs/ai-features-configuration.md

AI features — configuration and flows (high level)

This document describes how customer-facing AI is wired today: entry points, major pipeline steps, configuration stored on Store, and known gaps. Use it when changing ticket creation, Gmail behavior, or module gating.

Surfaces

Surface	Primary code	Notes
Gmail inbound	src/lib/gmail/emailProcessor.ts, webhook src/app/api/webhooks/gmail/route.ts	Processes one unread message; builds a reply via generateAutoReplyPreview and sends it.
Storefront widget	src/app/api/storefront-chat/messages/route.ts, src/lib/ai/storefrontGroq.ts	Public API; resolves store by shop domain; runs the same L1 orchestrator as email with channel: "widget".

Gmail reply composition (generateAutoReplyPreview)

Rough order:

1. Safety — screenInboundEmailForAbuse; flagged messages get a minimal HTML response and no order data.
2. Classification — classifyCustomerEmail (Groq) yields Gmail intent/mood for logging and guardrails; order-context lines are built with heuristics in the same file (when to load cached orders, when to ask for order number first, off-topic detection, etc.).
3. L1 orchestrator — If not skipped (off-topic, too sparse, needs order id first, hint unmatched), runL1Orchestrator runs with channel: "email" and emailFrom set to the sender.
4. HTML fallbacks — If L1 returns empty text, built-in HTML snippets apply (off-topic boundary, need order id, hint unmatched, minimal acknowledgment). Vendor-editable HTML templates were removed; there is no DB template fallback.

Relevant store fields on this path: businessName, email, aiModules, modulePolicies (see below).

L1 orchestrator (runL1Orchestrator)

Single implementation for widget and email:

1. Retrieval — getBlendedStorefrontContext blends knowledge chunks / FAQs for the prompt context.
2. Intent → module — routeCustomerIntent (Groq JSON) maps the customer message to an L1Module.
3. Module gating — parseAiModulesJson + isModuleEnabled. Disabled modules fall back to FAQ. FAQ is always treated as enabled (cannot be turned off via JSON). UNKNOWN stays enabled for routing stability.
4. Pillar — Each module has a pillar in MODULE_MANIFESTS: K (knowledge), T (transactional / DB), X (ticket handoff copy), CAT (catalog metafields).
5. Verification — Widget: OTP-verified session on StorefrontChatConversation (asserted email + expiry). Email: trust From as customer email for order lookup (see runL1 and order tools).
6. Tools — Orders: orderTools. Products: productTools for search + product metafield summaries in L1 (no separate category-metadetails path in the vendor UI).
7. Reply — Mostly composeReply (Groq) over assembled facts. For pillar X, the customer sees fixed handoff copy from ticketHandoffText — no ticket row is created in the database.

Vendor UI for aiModules and modulePolicies: dashboard JUNO Engine → Modules; persistence via GET/PATCH /api/stores/[storeId].

Knowledge base (separate from module toggles)

• Mode and content — Store.knowledgeBaseMode, knowledgeTemplate JSON, documents, FAQs, structured chunks. APIs under src/app/api/stores/[storeId]/knowledge-template and KB subroutes.
• Public query — e.g. src/app/api/stores/[storeId]/kb/query/route.ts for RAG-style use.

Module toggles do not turn off the knowledge base; they only restrict which L1 modules can run after routing.

Known gaps (intentional follow-ups)

1. Ticket-led (X) flows — The orchestrator acknowledges and promises human follow-up but does not create a ticket entity. Vendor Tickets in the dashboard are derived from EmailLog, not from L1.
2. Spec vs router — Vendor policy text is stored per L1Module in Store.modulePolicies (AI modules UI). The intentRouter only emits declared modules. Extending automation requires adding a module in types, MODULE_MANIFESTS, DEFAULT_ENABLED in aiModules.ts, and orchestrator branches in runL1.ts.
3. Gmail vs widget parity — Same L1 core; Gmail adds a pre-L1 classification layer and different skip rules for when L1 runs.

Environment / models

• Groq and related env vars are used by groqClient, gmailGroq, intentRouter, and composeReply.
• Rate limits and leases for Gmail inbound: gmailAutoReplyGuards.