Collaborative Vocabulary Bot

Collaborative Vocabulary Bot is a Telegram assistant that helps small learning groups collect, review, and explore new words together. The bot blends conversational flows, scheduled reminders, and AI-powered lookups to make vocabulary practice part of your daily routine.

✨ Features

• Guided word capture – /w starts a short flow to capture a word and its definition from any authorized participant.
• One-tap AI enrichment – /sw <word> fetches a pronunciation, meaning, synonyms, antonyms, and usage examples from Google Gemini and stores the result automatically.
• Ask anything – /sq <query> pipes arbitrary language questions to Gemini and shares the response in chat.
• Smart search – /f <term> finds existing entries by word or definition so the group can revisit recent discoveries.
• Daily rituals – Morning prompts share motivational quotes and fresh word suggestions, while evening recaps summarize the team’s additions.
• Safety guardrails – Only the Telegram user IDs listed in AUTHORIZED_USERS can interact with the bot.

🧱 Architecture

• Runtime: Node.js 18 hosted on Vercel serverless functions.
• Database: PostgreSQL managed through Prisma ORM.
• Messaging: node-telegram-bot-api sends formatted Markdown messages to Telegram chats.
• AI integration: @google/generative-ai (Gemini 1.5 Flash) powers dictionary-style lookups, general queries, and daily learning tips.
• API surface: Vercel edge endpoints under /api handle webhook updates, cron-style prompts, and manual utilities.

/api
├── bot.js            # Telegram webhook entry point and command handling
├── morning-promt.js  # Morning motivational + suggestion broadcast
├── evening-recap.js  # End-of-day summary broadcast
├── search-word.js    # Standalone AI lookup + persistence endpoint
├── search-query.js   # Generic Gemini-powered query endpoint
└── test-db.js        # Health check for database connectivity

Shared helpers live in lib/ (Telegram client setup, Prisma client, Gemini helpers), and the Prisma schema lives in prisma/schema.prisma.

⚙️ Prerequisites

• Node.js 18+
• PostgreSQL database
• Telegram bot token (via BotFather)
• Google Gemini API key
• Vercel CLI (for local development or deployment)

🔐 Required environment variables

Create a .env file (or configure environment variables in Vercel) with the following keys:

Variable	Description
TELEGRAM_BOT_TOKEN	Token issued by BotFather for your Telegram bot
AUTHORIZED_USERS	Comma-separated list of Telegram user IDs that can use the bot
GEMINI_API_KEY	Google Generative AI API key (Gemini 1.5 Flash)
DATABASE_URL	PostgreSQL connection string used by Prisma

Tip: When deploying to Vercel, add the variables in the project settings and redeploy so the serverless functions pick them up.

🚀 Local development

1. Install dependencies

   npm install

2. Generate the Prisma client (automatically happens on install, but safe to rerun)

   npx prisma generate

3. Apply migrations (creates the Word table if it does not exist)

   npx prisma migrate deploy

4. Start the local dev server (runs Vercel’s serverless emulator)

   npm run dev

5. Expose the webhook – Use a tunneling tool such as ngrok to forward https://<random>.ngrok.io/api/bot to your local dev server and set the Telegram webhook URL.

🧪 Verifying your setup

• Visit /api/test-db to confirm Prisma can connect to the database.
• Trigger a manual POST to /api/bot with a sample Telegram update to validate the command flow.
• Hit /api/morning-promt and /api/evening-recap via curl to emulate the scheduled reminders.

☁️ Deployment

1. Push the repository to GitHub and link it to a Vercel project.
2. Configure the environment variables under Settings → Environment Variables.
3. Provision your PostgreSQL database (e.g., Neon, Supabase, or Railway) and run npx prisma migrate deploy via a Vercel deployment hook or CI job.
4. Redeploy; Vercel will build the project and expose the API endpoints.
5. Point your Telegram bot webhook to https://<your-vercel-domain>/api/bot.
6. (Optional) Schedule HTTPS cron jobs (Vercel Cron, GitHub Actions, or any scheduler) that call /api/morning-promt and /api/evening-recap at your preferred times.

📚 Database schema

model Word {
  word          String   @id @unique
  description   String
  addedByUserId BigInt
  addedByName   String
  createdAt     DateTime @default(now()) @db.Timestamptz(3)
}

Each saved word stores the contributor’s Telegram ID and display name, making it easy to credit contributors in recaps.

🤝 Collaboration notes

• Use /help inside Telegram to see the live command menu.
• The bot formats outbound messages using Markdown; when editing strings, escape Markdown-reserved characters.
• Prisma uses a singleton pattern to reuse connections across serverless invocations.

🧭 Roadmap ideas

• Add spaced-repetition reminders based on individual learning progress.
• Expose a web dashboard for browsing the shared vocabulary list.
• Track word difficulty levels and tag suggestions accordingly.

---

Built with ❤️ to make collaborative language learning effortless.