菜单
Architecture map for the WhatsApp teaching-assistant bot — what it does, how the pieces fit, and where to drill in. The orientation hub for development, debugging, and extension.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Classroom-observation coaching pipeline — pluggable scoring frameworks (OECD/HOTS/TEACH/FICO), the async queue worker, lesson-plan integration, and session debugging.
Trace any feature end to end — webhook → handler → service → queue → worker → DB → storage → delivery — to find where a user's request actually broke. The map that points you at the right service, worker, table, and skill for each feature.
How the bot logs — structured single-line JSON to the console, correlation IDs that thread a request across handler/queue/worker, semantic events, and an optional external log backend. Use when adding logging or wiring observability.
Pre-merge defensive checks for recurring, predictable bug classes — run before merging code that (a) emits new interactive button/list/Flow IDs, (b) edits or sends a Flow, (c) writes new enum/status values, (d) chains Supabase update+filter+select, (e) sends to a dormant user, or (f) tracks files toxic to a fresh clone. Each class has a concrete grep/SQL pre-flight and the failure mode it prevents.
A/B testing via a Thompson-sampling multi-armed bandit. DB-driven tests (ab_tests / ab_test_variants / ab_test_events) that learn the best-performing variant online. Use when adding or measuring a message/content experiment.
Query the bot's Postgres database with a read-only role. Use when analysing user metrics, debugging DB state, or exploring the schema. Column names: phone_number (not phone), first_name (not name) in the users table.
| name | digital-coach |
| description | Architecture map for the WhatsApp teaching-assistant bot — what it does, how the pieces fit, and where to drill in. The orientation hub for development, debugging, and extension. |
Up: .claude/CLAUDE.md (config & skills router) · See also: debugging
This is the orientation hub. Read it first to understand how the bot is shaped, then drill into a folder router or a feature skill. Don't load everything at once — be strategic about context.
An AI WhatsApp assistant for teachers. Core capabilities:
It is region-agnostic: language, curriculum, and which features are switched on are all driven by configuration, never hard-coded. See the presence-based gating model below.
| Layer | Choice |
|---|---|
| Runtime | Node.js + Express |
| Messaging | WhatsApp Cloud API (webhook in, Graph API out) |
| LLM | Pluggable through bot/shared/services/llm-client.js (e.g. an OpenRouter gateway) |
| Datastore | Postgres (via Supabase) |
| Async work | Pluggable queue — QUEUE_DRIVER=sqs (default) or bullmq (Redis-only). See bot/CLAUDE.md. |
| STT / TTS | External providers, configured by env |
Start from the routers — they are kept accurate to the shipped code:
QUEUE_DRIVER, the repo map.The request path, end to end:
WhatsApp webhook → bot/whatsapp-bot.js (entry)
→ bot/shared/handlers/*.handler.js (route by message type)
→ bot/shared/services/* (business logic; LLM, STT, TTS, persistence)
→ enqueue long jobs onto the queue
→ bot/workers/*.js (transcribe, generate, score, deliver)
There is no tier system. A feature turns on when the env vars it needs are present — checked through
bot/shared/config/feature-availability.js. Set the
coaching keys and coaching works; leave them unset and the bot degrades gracefully. Per-region toggles can
additionally be stored in the region_features table (fail-open). This is what makes the same codebase
deployable by anyone with their own credentials — see .env.template.
| You want to… | Go to |
|---|---|
| Set up locally | .env.template + infrastructure/CLAUDE.md (bootstrap the DB) |
| Understand the bot code | bot/CLAUDE.md |
| Debug a failing request | debugging |
| Work on coaching | coaching |
| Work on registration | registration |
When documenting or communicating about the bot: technical accuracy over marketing; problem → solution → trade-offs (be transparent about limitations); show code, don't just describe it; note when a fact was last verified, since pricing and provider behaviour drift. When in doubt, check the git history and the running service's logs for the latest state.