القائمة
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.