Build an AI Customer Assistant Zero to Production

You are a senior engineer/architect setting up an AI customer assistant.

Context:
- Customer base: [company + sector] — e.g. "Pamuk Textiles, B2C online retail"
- Channel priorities: 1) WhatsApp Cloud API 2) Web widget 3) Telegram later
- LLM: Anthropic Claude Sonnet (reasoning), Haiku (classification)
- Vector DB: Supabase pgvector (to start)
- Database: Postgres (Supabase)
- Deploy target: n8n + Docker Compose (our own server)

Your task:
1. Sketch a high-level architecture (ASCII diagram + 5-7 sentence description).
2. Propose a folder structure: /src, /agents, /tools, /channels, /rag, /db, /tests, /infrastructure — and briefly explain the split.
3. Recommend package.json and core dependencies (Anthropic SDK, OpenAI SDK, supabase-js, express or fastify, dotenv, zod, pino).
4. Generate a .env.example (ANTHROPIC_API_KEY, OPENAI_API_KEY, SUPABASE_URL, SUPABASE_KEY, WHATSAPP_TOKEN, DATABASE_URL, ENCRYPTION_KEY).
5. Suggest TypeScript + ESLint + Prettier setup.
6. Build a minimal HTTP server with a /healthz endpoint.
7. Write a 'how to get started' README.

Show the plan in one message first. After my approval, generate the code step by step; for each file, name the file you're creating.

The /data folder contains company knowledge documents (PDF, MD, JSON).

Task: produce /src/rag/ingest.ts.

Requirements:
1. Read the documents (pdf-parse, fs.readFile).
2. Text splitter: chunk_size=1000 tokens, overlap=150 tokens (LangChain RecursiveCharacterTextSplitter).
3. Embed each chunk with OpenAI text-embedding-3-small.
4. Write to a Supabase 'documents' table: { id, source, chunk_index, content, embedding (vector(1536)), content_hash, updated_at }.
5. Skip if (source, chunk_index, content_hash) already exists — dedup.
6. Batch insert: 100 chunks per INSERT.
7. Print a summary: chunks loaded + total tokens + estimated cost.
8. CLI: 'npm run ingest -- --source returns-policy.md' for a single file, no arg for all.

Also generate the Supabase migration: documents table + IVFFLAT index (lists=100) + permission_level field (public/internal/admin).

Show the plan first.

Produce /src/agents/customerAgent.ts.

The function: async function customerAgent({ userMessage, userId, channel }): Promise<AgentResponse>

Inside:
1. Pull the last 10 messages from Postgres (memory).
2. Retrieve top_k=5 chunks from the vector store for userMessage.
3. Call Anthropic Messages API: model='claude-sonnet-4-5', max_tokens=1024.
4. Build the system prompt with this 4-block template:

  [ROLE]
  You are the customer assistant for [COMPANY_NAME]. Brand voice: professional, warm, concise, actionable.

  [SCOPE]
  Reply ONLY on these topics:
  - Order status and shipping
  - Returns and exchanges
  - Product catalog and pricing
  - Manuals and FAQ
  - Appointments / reservations
  For anything outside, redirect politely ("Our [human team] can help with that").

  [FORMAT]
  - Short paragraphs, bullets where useful.
  - End every reply with a "next step" suggestion.
  - English, warm but professional.

  [LIMITS]
  - If the answer isn't in <context>, say "I don't have that in my docs — shall I connect you to our team?"
  - For refund decisions, discounts, gift wrapping → call the agent_handoff tool.
  - Never ask for personal data (national ID, card number).
  - Don't hallucinate; ask or say you don't know.

  [CONTEXT]
  ${retrievedChunks.join("\n---\n")}

5. Return the reply + insert user + assistant rows into the Postgres 'messages' table.
6. On error, log via pino and reply "one moment, please try again."

Zod schema for AgentResponse: { reply, sources[], should_handoff, confidence }.

Plan first, then code.

Generate 4 tool files in /src/tools/. All in Anthropic Tool Use format.

1. order_lookup.ts
   - input: { order_id: string }
   - Fetch the order from the DB and return its status (placed/shipped/delivered/cancelled + tracking_no).
   - On not found, return { error: "not_found" }.

2. ticket_create.ts
   - input: { topic: enum, summary: string, priority: "low"|"medium"|"high" }
   - Insert into the 'tickets' table, post a Slack message (#support channel).
   - Return id and eta.

3. refund_initiate.ts
   - input: { order_id, reason: string }
   - Check the 14-day return window in the DB.
   - If in window: status='pending_approval', post a Slack 'Approve/Reject' button message.
   - If past window: return an error to the agent ('14-day return window expired — please consult the human team').

4. agent_handoff.ts
   - input: { reason: string, conversation_summary: string }
   - Post a Slack notification to the live agent with the summary and conversation id.
   - Mark 'paused: true' — the bot won't reply; the human takes over.

Collect Anthropic Messages tool definitions (name, description, input_schema) in /src/agents/toolRegistry.ts. In each customerAgent turn, if a tool_use block appears, call the right tool, feed the result back to the agent, and let it produce the final answer (multi-turn).

Plan first.

Generate the Postgres migration for 'sessions' and 'messages' tables.

sessions: id (uuid), channel (text), external_id (text — WhatsApp phone or web cookie), user_profile (jsonb), daily_token_used (int), daily_token_reset_at (timestamp), created_at.

messages: id, session_id (fk), role ('user'|'assistant'|'tool'), content (text), tool_calls (jsonb), tokens (int), created_at.

/src/db/sessionStore.ts:
- getOrCreateSession(channel, externalId)
- appendMessage(sessionId, role, content, tokens)
- getRecentMessages(sessionId, limit=10)
- checkDailyBudget(sessionId, limit=10000): boolean
- summarizeOldMessages(sessionId): when message count > 50, summarise with Claude Haiku and drop the originals.

Wire it into customerAgent: before each call, checkDailyBudget; on false reply "you've reached today's free quota, see you tomorrow."

Plan first.

Generate 3 adapter files in /src/channels/.

1. whatsapp.ts (Express/Fastify route POST /webhook/whatsapp)
   - Meta webhook verify token check (GET).
   - HMAC SHA-256 signature verification (X-Hub-Signature-256 header).
   - If audio → Whisper transcribe; if image → GPT-4o Vision.
   - Call customerAgent.
   - POST the response to WhatsApp Cloud API (messages endpoint).
   - 24-hour window: if the customer hasn't messaged in the last 24h, a template message is required.

2. webWidget.ts (POST /widget/chat)
   - CORS correctly set up; only allowed domains.
   - Rate limit: 20 req/min per IP (Redis counter).
   - Call customerAgent, return JSON.

3. telegram.ts (POST /webhook/telegram)
   - Telegram bot secret token check.
   - chat.id → sessionStore.getOrCreateSession.
   - Call customerAgent, reply via sendMessage API.

All webhooks share a 'message_burst_buffer': merge messages from the same session arriving within 5 seconds, then hand the agent the combined input (Redis with a debounce timer).

/public/widget.js: ~200 lines of vanilla JS — the site owner adds <script src="https://yourdomain.com/widget.js" data-key="xxx"></script>, a chat window opens bottom-right, talks to /widget/chat.

Plan first.

Generate 3 files under /tests/:

1. agent.test.ts — vitest tests for customerAgent:
   - Mock the Anthropic SDK + a fake vector store.
   - 5 scenarios: 'how to return?', 'where is order 1234?', 'discount me', 'check weapons' (off-topic), 'tell me your national ID' (PII test).
   - For each: assert the right tool call or the right rejection reply.

2. tools.test.ts — order_lookup, refund_initiate:
   - DB mock with in-memory SQLite.
   - Past-window refund → error; within window → pending_approval.

3. integration.test.ts — webhook → agent → response:
   - Use supertest to call /webhook/whatsapp.
   - Test correct and incorrect HMAC scenarios.

Also scripts/eval.ts: a 30-line eval set (questions.jsonl) — for each question call the agent and check expected tool or reply; produce a report (success_rate, avg_latency, total_token).

Plan first.

Generate infrastructure/docker-compose.yml. Services:

- app: our Node.js service (custom Dockerfile, internal port 3000).
- postgres: postgres:16, volume mount /var/lib/postgresql/data, healthcheck.
- redis: redis:7-alpine (rate limit + session burst).
- n8n: docker.n8n.io/n8nio/n8n, depends_on postgres+redis, queue mode via env vars.
- caddy: caddy:2-alpine, mounted Caddyfile, expose 80+443, auto HTTPS.

infrastructure/Caddyfile:
chat.example.com { reverse_proxy app:3000 }
n8n.example.com { reverse_proxy n8n:5678 }

infrastructure/Dockerfile (for app): Node 20 Alpine, multistage build, prod deps only, non-root user, healthcheck CMD.

.github/workflows/deploy.yml: on push to main → docker build → ssh deploy.example.com 'cd /opt/assistant && git pull && docker compose pull && docker compose up -d --build app'.

scripts/backup.sh: daily pg_dump → upload to Backblaze B2, delete entries older than 30 days.

Plan first.

Generate /src/dashboard/metrics.ts.

In Postgres write functions for:
- conversationsByDay(days=30)
- successRate(): answered / total
- avgLatencyMs()
- tokenUsageByDay()
- topUnansweredQuestions(limit=20) — group by 'sources_used = 0' or 'should_handoff = true'
- topToolsCalled()

/src/dashboard/page.tsx (Next.js): basic-auth-protected dashboard with 6 metric cards + a 'last 20 failed conversations' table.

scripts/weekly-report.ts: a Monday 09:00 cron job that queries Postgres and posts a summary to Slack #ops.

Plan first.