mirror of
https://github.com/tiennm99/miti99bot-js.git
synced 2026-05-14 15:53:33 +00:00
tiennm99
e2e3112eb5
Phase 08: Complete documentation pass for MongoDB Atlas migration. - Create docs/cost-tracking.md: Cost monitoring, upgrade triggers, monthly checklist - Create docs/project-changelog.md: Full migration summary with phase breakdown - Update docs/architecture.md section 8: Describe dual-write era, MongoDB store layers - Update docs/code-standards.md: Add Persistence section for storage factory patterns - Update docs/codebase-summary.md: Reflect MongoDB as primary, update test count (733) - Update README.md: Storage section now describes MongoDB + dual-write during migration - Update CLAUDE.md: Architecture section references MongoDB instead of KV/D1 - Update tests/fakes/fake-mongo.js: Document frozen surface (Phase 02-08 API) Verified: - All 733 tests passing - Lint + secret-leak check pass - npm run register:dry succeeds - Auto-pause concern satisfied: trading (17:00), lolschedule (01:00), drift-verifier (hourly) all write to Mongo - Roadmap verified migration NOT listed (future-only per user feedback) Post-Phase-07 cutover: dual-write collapses, KV/D1 deleted, MongoDB becomes sole backend.
79 lines
4.2 KiB
Markdown
79 lines
4.2 KiB
Markdown
# Codebase Summary
|
||
|
||
## Overview
|
||
|
||
Telegram bot on Cloudflare Workers with a plug-n-play module system. grammY handles Telegram API; modules register commands with three visibility levels. **During migration (Phase 08):** Data is stored in MongoDB Atlas M0 (behind a prefixed `KVStore` interface for KV data, `MongoTradesStore` for trading ledger). Dual-write to Cloudflare KV/D1 is active for safety; post-Phase-07 cutover, MongoDB becomes sole backend.
|
||
|
||
## Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|-------|-----------|
|
||
| Runtime | Cloudflare Workers (V8 isolates) |
|
||
| Bot framework | grammY 1.x |
|
||
| Storage | MongoDB Atlas M0 (primary, via official driver). Cloudflare KV + D1 (secondary, for dual-write safety during migration). |
|
||
| AI inference | Workers AI binding (`env.AI`) |
|
||
| Linter/Formatter | Biome |
|
||
| Tests | Vitest |
|
||
| Deploy | Wrangler CLI |
|
||
|
||
## Active Modules
|
||
|
||
| Module | Commands | Storage | Crons | Description |
|
||
|--------|----------|---------|-------|-------------|
|
||
| `util` | `/info`, `/help`, `/stickerid` (private) | — | — | Bot info, command help renderer, sticker file_id echo helper |
|
||
| `misc` | `/ping`, `/mstats`, `/fortytwo` | MongoDB KVStore | — | Health check + DB demo stub |
|
||
| `trading` | `/trade_topup`, `/trade_buy`, `/trade_sell`, `/trade_convert`, `/trade_stats`, `/history` | MongoDB (trades + portfolio + symbol cache) | Daily 5PM trim | Paper trading — VN stocks with dynamic symbol resolution |
|
||
| `wordle` | `/wordle`, `/wordle_new`, `/wordle_giveup`, `/wordle_stats` | MongoDB KVStore | — | 5-letter word guessing game. 14,855-word dict |
|
||
| `loldle` | `/loldle`, `/loldle_giveup`, `/loldle_stats` | MongoDB KVStore | — | Classic-mode LoL champion guesser. Data synced from `tiennm99/loldle-data` |
|
||
| `lolschedule` | `/lolschedule_today`, `/lolschedule_week`, `/lolschedule_subscribe`, `/lolschedule_unsubscribe` | MongoDB KVStore | Daily 01:00 UTC | LoL esports schedule + daily digest subscriptions |
|
||
| `semantle` | `/semantle`, `/semantle_giveup`, `/semantle_stats` | MongoDB KVStore | — | English semantic word guessing via hosted word2sim service |
|
||
| `doantu` | `/doantu`, `/doantu_hint`, `/doantu_giveup`, `/doantu_stats` | MongoDB KVStore | — | Vietnamese semantle via hosted phow2sim service |
|
||
| `twentyq` | `/twentyq`, `/twentyq_giveup`, `/twentyq_stats` | MongoDB KVStore | — | Reverse-Akinator yes/no game. Workers AI (`@cf/google/gemma-4-26b-a4b-it`) generates round-start category+hint and judges each turn via one-line JSON |
|
||
|
||
## Key Data Flows
|
||
|
||
### Command Processing
|
||
```
|
||
Telegram update → POST /webhook → grammY secret validation
|
||
→ getBot(env) → dispatcher routes /cmd → module handler
|
||
→ handler reads/writes KV via db.getJSON/putJSON (or D1 via sql.all/run)
|
||
→ ctx.reply() → response to Telegram
|
||
```
|
||
|
||
### Scheduled Job (Cron)
|
||
```
|
||
Cloudflare timer fires (e.g., "0 17 * * *")
|
||
→ scheduled(event, env, ctx) handler
|
||
→ getRegistry(env) → load + init modules
|
||
→ dispatchScheduled(event, env, ctx, registry)
|
||
→ filter matching crons by event.cron
|
||
→ for each: handler reads/writes D1 via sql.all/run (or KV via db)
|
||
→ ctx.waitUntil(promise) keeps handler alive
|
||
```
|
||
|
||
### Deploy Pipeline
|
||
```
|
||
npm run deploy
|
||
→ wrangler deploy (upload to CF, set env vars and bindings)
|
||
→ npm run db:migrate (apply any new migrations to D1)
|
||
→ scripts/register.js → buildRegistry with stub KV
|
||
→ POST setWebhook + POST setMyCommands to Telegram API
|
||
```
|
||
|
||
## External Dependencies
|
||
|
||
| Dependency | Purpose | Version |
|
||
|-----------|---------|---------|
|
||
| `grammy` | Telegram Bot API framework | ^1.30.0 |
|
||
| `@biomejs/biome` | Linting + formatting (dev) | ^1.9.0 |
|
||
| `vitest` | Test runner (dev) | ^4.1.4 |
|
||
| `wrangler` | Cloudflare Workers CLI (dev) | ^4.84.0 |
|
||
|
||
## Module Documentation
|
||
|
||
Each module maintains its own `README.md` with commands, data model, and implementation details. See `src/modules/<name>/README.md`.
|
||
|
||
## Tests
|
||
|
||
`npm test` runs the full vitest suite (run in ~10 seconds — 733 tests). Structure: one folder per module under `tests/modules/<name>/`, shared fakes under `tests/fakes/` (fake-mongo, fake-kv-namespace, fake-d1, fake-bot, fake-modules, fake-ai). No workerd, no Telegram fixtures — pure-logic unit tests with injected fakes. See `tests/fakes/fake-mongo.js` for the frozen surface implemented during Phase 02–08.
|