Overview
LexicalGem is a Telegram bot that teaches you unusual / elegant / fun words on demand with /word. It’s built like a “real” service: modular components, structured logging, validation, and careful behavior design (like no-repeat cycling so the word set is exhausted before repeating).
What it demonstrates
- Bot engineering with clean separation of concerns (manager / handler / services)
- “No repetition” logic with cycle tracking + user progress feedback
- Operational hygiene: logging levels, graceful shutdown, recovery
- Maintaining a word database externally (
src/words.json) for easy extension
Key features
/wordreturns a rare word + definition (+ progress tracking)- No-repeat cycling: shows all words before repeating
/stats,/help,/start+ additional commands (v2 feature set)- External word DB in JSON for easy edits
- Professional logging (levels + color) + robust error handling
- Health monitoring and uptime/user metrics
Try it live
Quickstart
Bash
git clone https://github.com/casaisdev/LexicalGem.gitSee the README on GitHub for setup details.
Environment variables
Create .env from the example and set your bot token:
Bash
cp env.example .env
# required
BOT_TOKEN_CODE=YOUR_TOKEN
# optional
DEBUG=false
NODE_ENV=productionProject structure (high-level)
src/index.js: entrypointsrc/bot/CommandHandler.js: command parsing + routingsrc/services/WordService.js: word selection + no-repeat cyclingsrc/utils/Logger.js: structured loggingsrc/words.json: word database
Notes
- Keep your bot token private (never commit
.env). - Add more words by editing
src/words.jsonand restarting the bot. - If the bot fails to start, double-check
BOT_TOKEN_CODEand your network connection.
Next steps
If I were to extend LexicalGem further:
- Persist user history/stats (SQLite/Postgres) instead of in-memory tracking
- Add user preferences (difficulty, categories, scheduling)
- Add basic unit tests for
WordServiceandUserService - Expand the word set + add sources (external dictionary API)