From f613d83b40267d208fc8c555e9fb59de2953d077 Mon Sep 17 00:00:00 2001 From: yiekheng Date: Sat, 9 May 2026 17:10:48 +0800 Subject: [PATCH] docs: add top-level README --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b933d7 --- /dev/null +++ b/README.md @@ -0,0 +1,81 @@ +# cm WhatsApp Reminder Bot + +Self-hosted WhatsApp reminder bot. Pairs multiple WhatsApp accounts via Telegram-delivered QR codes and sends scheduled reminders to groups. + +## Status + +**Plan 1 complete.** Foundation, DB schema, and Telegram-driven WhatsApp pairing are working end-to-end. Reminder scheduling, the web dashboard, and production deploy are upcoming plans (`docs/superpowers/plans/`). + +What's working today: + +- Single-operator Telegram bot with a whitelist + audit log of every command. +- BotFather-style menu navigation: `/menu` opens a single message that edits in place as you navigate. +- Pair a new WhatsApp account with `/menu` → 📡 Pair New → reply with a label. QR is delivered to Telegram and refreshed in place as it expires. +- Browse paired accounts with 📒 Accounts. Tap an account → see groups, send a test text message, or unpair. +- Group sync runs at pairing and on every Baileys `groups.upsert` / `groups.update` event, plus a manual 🔄 Refresh button. Removed groups are pruned automatically. +- Auto-reconnect on transient drops; restart-survival via Baileys `useMultiFileAuthState` (no QR rescan needed across container restarts as long as WhatsApp hasn't logged the device out). + +## Host requirements + +Only Docker. No host Node, pnpm, or any other language toolchain — everything runs in containers via the long-lived `tools` service. + +## Architecture in one paragraph + +Two app containers and one external dependency. `bot` (Node.js) holds the live Baileys WhatsApp sessions, the grammy Telegram bot, and (in plan 2) a pg-boss scheduler. `web` (Next.js, plan 3) is stateless UI + API. `tools` is a long-running Node 22 + pnpm sidecar used for installs/tests/typechecks/migrations so the host doesn't need a Node toolchain. Postgres lives external at `192.168.0.210` in a `wabot` database. All cross-service communication goes through Postgres (`LISTEN/NOTIFY` for events, table writes for state). + +Full design spec: [`docs/superpowers/specs/2026-05-03-whatsapp-bot-design.md`](docs/superpowers/specs/2026-05-03-whatsapp-bot-design.md) + +## Quick start (dev) + +Prerequisites: Docker, the `wabot` database + `waBot` role on `192.168.0.210` (with a `pg_hba.conf` line permitting `192.168.0.0/24`), and a Telegram bot token from `@BotFather`. + +```bash +# 1. Configure env +cp envs/.env.example .env.development +# edit .env.development: real DATABASE_URL, TELEGRAM_BOT_TOKEN, your TG user ID +scripts/gen_auth_secret.sh --write + +# 2. Bring up the tools container, install deps +NO_SUDO=1 scripts/dev.sh up +NO_SUDO=1 scripts/dev.sh pnpm install + +# 3. Apply migrations and seed your operator row +NO_SUDO=1 scripts/db.sh migrate +NO_SUDO=1 scripts/db.sh seed + +# 4. Watch the bot service +NO_SUDO=1 scripts/dev.sh logs bot +``` + +In Telegram, message your dev bot `/menu`, tap **📡 Pair New**, reply with a label, scan the QR. + +`NO_SUDO=1` is the right setting if your user is in the `docker` group (the default for this repo). Drop it if you need `sudo docker`. + +## Layout + +- `apps/bot/` — Node service: Baileys WhatsApp + grammy Telegram + (later) pg-boss scheduler +- `apps/web/` — Next.js dashboard (plan 3) +- `packages/db/` — Drizzle schema and migrations +- `packages/shared/` — cross-app helpers (rrule, media paths, timezones) +- `docs/superpowers/specs/` — design specs and manual test runbooks +- `docs/superpowers/plans/` — implementation plans +- `docker/` — Dockerfiles (`tools.Dockerfile`, `bot.Dockerfile`, `web.Dockerfile` placeholder) +- `scripts/` — `dev.sh`, `db.sh`, `gen_auth_secret.sh`, plus stubs for plans 2/4 + +## Scripts + +All `pnpm`/`tsx`/`drizzle-kit` invocations run inside the `tools` container, so no host Node is needed. + +| Script | Purpose | +|---|---| +| `scripts/dev.sh up\|down\|logs\|status\|build\|exec\|pnpm\|shell\|restart-bot` | Stack lifecycle and tools-container shell | +| `scripts/db.sh migrate\|generate\|studio\|seed\|reset` | Drizzle migration helper | +| `scripts/gen_auth_secret.sh [--write]` | Generate `AUTH_SECRET` (host-only, no Node needed) | +| `scripts/publish.sh` | Push to Gitea registry — implemented in plan 4 | +| `scripts/link-account.sh` | CLI pairing without Telegram — implemented in plan 2 | + +Set `NO_SUDO=1` if your user is in the docker group (recommended). + +## Next plan + +`docs/superpowers/plans/-reminder-scheduling.md` — pg-boss, reminder CRUD via Telegram, fire-reminder handler, sender (text/image/video), retry policy, run history.