mirror of https://github.com/tiennm99/miti99bot.git synced 2026-04-17 15:20:58 +00:00

Files

tiennm99 4277f11c48 docs: add CLAUDE.md and project documentation

Add CLAUDE.md for AI assistant context. Create four new docs:
deployment-guide.md (full deploy flow + secret rotation + rollback),
code-standards.md (formatting, naming, module conventions, testing),
codebase-summary.md (tech stack, modules, data flows, external APIs),
development-roadmap.md (completed phases + planned work).

2026-04-14 15:28:53 +07:00

2.8 KiB

Raw Blame History

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. Data stored in Cloudflare KV behind a prefixed KVStore interface.

Tech Stack

Layer	Technology
Runtime	Cloudflare Workers (V8 isolates)
Bot framework	grammY 1.x
Storage	Cloudflare KV
Linter/Formatter	Biome
Tests	Vitest
Deploy	Wrangler CLI

Active Modules

Module	Status	Commands	Description
`util`	Complete	`/info`, `/help`	Bot info and command help renderer
`trading`	Complete	`/trade_topup`, `/trade_buy`, `/trade_sell`, `/trade_convert`, `/trade_stats`	Paper trading with crypto, VN stocks, forex, gold
`misc`	Stub	`/ping`, `/mstats`, `/fortytwo`	Health check + DB demo
`wordle`	Stub	`/wordle`, `/wstats`, `/konami`	Placeholder for word game
`loldle`	Stub	`/loldle`, `/ggwp`	Placeholder for LoL game

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
→ ctx.reply() → response to Telegram

Trading Module Price Fetch

User sends /trade_buy → handler calls getPrice(db, symbol)
→ getPrices(db) checks KV cache (key: "prices:latest")
→ if stale (>60s): fetch CoinGecko + TCBS + ER-API in parallel
→ merge results, cache in KV → return price in VND

Deploy Pipeline

npm run deploy → wrangler deploy (upload to CF)
→ 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)	^2.1.0
`wrangler`	Cloudflare Workers CLI (dev)	^3.90.0

External APIs (Trading Module)

API	Purpose	Auth	Rate Limit
CoinGecko `/api/v3/simple/price`	Crypto + gold prices in VND	None	30 calls/min (free)
TCBS `/stock-insight/v1/stock/bars-long-term`	Vietnam stock close prices	None	Unofficial
open.er-api.com `/v6/latest/USD`	USD/VND forex rate	None	1,500/month (free)

Test Coverage

110 tests across 11 test files:

Area	Tests	What's Covered
DB layer	19	KV store, prefixing, JSON helpers, pagination
Module framework	33	Registry, dispatcher, validators, help renderer
Utilities	4	HTML escaping
Trading module	54	Symbols, formatters, portfolio CRUD, all 5 command handlers

2.8 KiB Raw Blame History