A Telegram birthday reminder bot — never forget a friend's birthday again.
💬 Community · 🟢 Good First Issues · 🐛 Issues
📋 Prerequisites: Java 25, Maven 3.9+, Docker Desktop, Telegram Bot Token (from @BotFather)
# 1. 📥 Clone
git clone https://github.com/Sunagatov/Festiva.git && cd Festiva
# 2. 🔧 Fill in your credentials
# edit TELEGRAM_BOT_TOKEN and TELEGRAM_BOT_USERNAME in .env
⚠️ Never commit.envwith real credentials. It is listed in.gitignore— keep it that way.
# Start only MongoDB
docker compose up -d mongoThen run the app from IntelliJ using the EnvFile plugin pointed at .env, or from the terminal:
# Linux / macOS:
set -a && source .env && set +a && mvn spring-boot:run# Start MongoDB + the bot together
docker compose up -d mongo
docker compose --profile bot up -d --buildProduction (MongoDB Atlas):
# Fill in .env.prod, then:
docker compose -f docker-compose.prod.yml up -d --build🧪 Run the tests:
mvn test✅ Tests use Testcontainers — Docker must be running.
Festiva is a Telegram bot that helps you manage and receive birthday reminders for your friends. Add friends with their birthdates, get notified on the day, the day before, and a week in advance. Supports Russian and English, milestone (jubilee) birthday highlights, and month-by-month birthday browsing.
🔔 Automatic reminders fire daily at 09:00 for birthdays today, tomorrow, and in 7 days.
| 📂 Category | 🔧 Technology |
|---|---|
| 💻 Language | Java 25 |
| 🏗️ Framework | Spring Boot 4.0, Spring Scheduling, Spring Actuator |
| 🗄️ Database | MongoDB Atlas, Spring Data MongoDB |
| 📨 Messaging | Apache Kafka (optional metrics) |
| 🤖 Telegram | telegrambots-longpolling + telegrambots-client 9.0 |
| 🧪 Testing | JUnit 5, Mockito, Testcontainers, AssertJ |
| 🚢 Deployment | Docker |
- 🔔 Automatic reminders — daily at 09:00 for birthdays today, tomorrow, and in 7 days
- 🎉 Milestone highlights — jubilee birthdays (multiples of 5) are called out specially
- 📅 Month-by-month browsing — scroll through birthdays by month
- 🌍 Bilingual — full support for 🇬🇧 English and 🇷🇺 Russian
- 👥 Friend management — add, edit, remove friends with birthdates and relationship labels
- 📦 Bulk import — add many friends at once via CSV file or paste
- 📤 Export — download your friends list as a CSV file
- 🔍 Search — find friends by name
- 📊 Stats — see your birthday statistics
- ⚙️ Settings — configure notification hour and timezone
- 🗑️ Account deletion — remove all your data
| 🎯 Command | 📝 Description |
|---|---|
/start |
Welcome message and command overview |
/menu |
Show the command menu |
/help |
Alias for /menu |
/about |
About Festiva |
/add |
Add a friend with their birthdate |
/addmany |
Bulk-add friends via CSV file or paste |
/importics |
Import birthdays from Google Calendar (.ics) |
/edit |
Edit a friend's name, date, or relationship |
/remove |
Remove a friend |
/list |
List all friends sorted by birthday |
/birthdays |
Browse birthdays by month |
/today |
See today's birthdays |
/upcomingbirthdays |
Birthdays in the next 30 days |
/jubilee |
Upcoming milestone birthdays (multiples of 5) |
/search |
Search friends by name |
/stats |
Birthday statistics |
/export |
Download friends list as CSV |
/settings |
Configure notification hour and timezone |
/language |
Switch between 🇬🇧 English and 🇷🇺 Russian |
/deleteaccount |
Delete all your data |
/cancel |
Cancel the current operation |
src/main/java/com/festiva/
├── 🤖 bot/ # BirthdayBot, CallbackQueryHandler, sub-handlers
├── 💬 command/
│ └── handler/ # All command handlers (Start, Add, Edit, …)
├── 👥 friend/
│ ├── api/ # FriendService interface
│ ├── entity/ # Friend, Relationship
│ └── repository/ # FriendMongoRepository
├── 🌐 i18n/ # Lang enum, Messages (EN + RU)
├── 📊 metrics/ # Kafka metrics sender
├── 🔔 notification/ # BirthdayReminder scheduler
├── 🗂️ state/ # UserStateService, BotState
└── 👤 user/ # UserPreference, UserPreferenceRepository
| Variable | Required | Description |
|---|---|---|
MONGO_URI |
✅ | MongoDB connection URI |
MONGO_DATABASE_NAME |
❌ | Defaults to FestivaDatabase |
TELEGRAM_BOT_TOKEN |
✅ | Token from @BotFather |
TELEGRAM_BOT_USERNAME |
✅ | Your bot's username |
APP_KAFKA_ENABLED |
❌ | true to enable Kafka metrics |
KAFKA_BOOTSTRAP_SERVERS |
❌ | Kafka server (metrics only) |
KAFKA_API_KEY |
❌ | Kafka API key |
KAFKA_API_SECRET |
❌ | Kafka API secret |
See .env for local defaults and .env.prod for the production template.
Each feature has a full spec covering user stories, functional & non-functional requirements, bot flows, state transitions, error messages, acceptance criteria, data model, security, observability, and known limitations.
| Feature | Spec |
|---|---|
| Add Friend | docs/features/add-friend.md |
| Bulk Add Friends | docs/features/bulk-add.md |
| Edit Friend | docs/features/edit-friend.md |
| Remove Friend | docs/features/remove-friend.md |
| List Friends | docs/features/list.md |
| Search Friends | docs/features/search.md |
| Export Friends | docs/features/export.md |
| Birthdays by Month | docs/features/birthdays-by-month.md |
| Today's Birthdays | docs/features/today.md |
| Upcoming Birthdays | docs/features/upcoming-birthdays.md |
| Jubilee Birthdays | docs/features/jubilee.md |
| Birthday Reminders | docs/features/birthday-reminders.md |
| Stats | docs/features/stats.md |
| Settings | docs/features/settings.md |
| Language | docs/features/language.md |
| Delete Account | docs/features/delete-account.md |
| Import from Google Calendar (.ics) | docs/features/import-ics.md |
🎉 Contributions are welcome.
| 🎯 Situation | 🚀 Action |
|---|---|
| 🐛 Found a bug | Open an issue with the bug label |
| 💡 Want a feature | Start a Discussion first |
| 👨💻 Ready to code | Pick a good first issue, comment "I'm on it" |
| 🔧 Big change | Comment on the issue before writing code — tickets may have hidden constraints |
📜 CC BY-NC 4.0 — free for educational and personal use with author attribution. Commercial use requires explicit written permission from the author (zufar.sunagatov@gmail.com).
- 💬 Telegram community: Zufar Explained IT
- 👤 Personal Telegram: @lucky_1uck
- 📧 Email: zufar.sunagatov@gmail.com
- 🐛 Issues: GitHub Issues
❤️