🚀 Work Rhythm - Spring Boot Telegram Scheduler Bot

Project Architecture

flowchart LR
    A[WorkRhythm Scheduler] -->|Cron trigger| B[TelegramBot]
    B -->|Send message| C[Registered Chat IDs]
    A -->|GET random quote| D[ZenQuotes API]
    A -->|POST translate| E[LibreTranslate API]
    F[Telegram User] -->|Send any message| B
    B -->|Persist chat id| G[chat-ids.txt]

Loading

Telegram Preview

Add your screenshot file at images/telegram-preview.png.

• ✅ Spring Boot-based Telegram bot that sends scheduled (cron) messages
• ✅ Motivation messages + random quotes + English -> Turkish translation
• ✅ Fast setup with Docker Compose (app + LibreTranslate)

Used Technologies in The Project:

---

📌 What Is This Project?

Work Rhythm is a Telegram bot that sends automated reminders to support daily and weekly work routines.

What it does:

• Sends scheduled workday messages (start, breaks, wrap-up, end of day)
• Adds a random motivational quote to the morning message
• Translates quote text into Turkish via LibreTranslate
• Automatically stores user chatId values and broadcasts to all registered chats

---

🧠 How It Works

Flow:

1) User sends any message to the bot
2) Bot stores the chatId in chat-ids.txt
3) Scheduler triggers at configured cron times
4) Bot sends messages to all registered chatIds
5) Morning trigger enriches message using ZenQuotes + LibreTranslate

---

⏰ Scheduled Jobs (Cron)

Times are based on server timezone. In Docker Compose, TZ=Europe/Istanbul is set.

Task	Cron	Description
Good Morning	0 0 9 * * MON-FRI	Good morning message + translated quote
Morning Break Start	0 30 10 * * MON-FRI	Short break reminder
Morning Break End	0 40 10 * * MON-FRI	Break end reminder
Lunch Break Start	0 30 12 * * MON-FRI	Lunch break start
Lunch Break End	0 30 13 * * MON-FRI	Lunch break end
Afternoon Break Start	0 0 15 * * MON-FRI	Afternoon break reminder
Afternoon Break End	0 10 15 * * MON-FRI	Afternoon break end
Wrap Up	0 30 16 * * MON-FRI	Daily wrap-up reminder
End Of Day	0 0 17 * * MON-FRI	End of workday message
Sunday Greeting	0 0 21 * * SUN	Sunday evening reminder
Sunday Greeting 2	0 10 23 * * SUN	Additional Sunday reminder

---

🛠️ Project Structure

src/main/java/com/workrhythm/
├── WorkRhythmApplication.java
├── bot/
│   ├── BotInitializer.java          # Registers Telegram bot session
│   └── TelegramBot.java             # Receives/sends messages + chatId persistence
├── config/
│   ├── AppConfig.java               # app.* properties
│   ├── TelegramConfig.java          # bot.* properties
│   └── RestClientConfig.java        # RestClient.Builder bean
├── dto/
│   ├── TranslateRequestDTO.java
│   ├── TranslateResponseDTO.java
│   └── ZenQuoteResponseDTO.java
├── scheduler/
│   └── WorkRhythmScheduler.java     # Cron jobs
└── service/
    ├── TranslationService.java      # LibreTranslate integration
    └── ZenQuoteService.java         # ZenQuotes integration

---

⚙️ Configuration

src/main/resources/application.yaml:

# Application Config
spring:
  application:
    name: work-rhythm

# Telegram Config
bot:
  name: <YOUR_TELEGRAM_BOT_NAME>
  token: <YOUR_TELEGRAM_BOT_TOKEN>
  chat-ids-file: chat-ids.txt

app:
  zen-quotes-api: https://zenquotes.io/api/random
  translation-api: http://localhost:5000/translate

Important Notes

• Each line in chat-ids.txt must contain one valid long value.
• Invalid text or a number outside the Java Long range can fail application startup.
• Do not commit your real bot token to the repository.

---

🚀 Setup and Run

1) Prerequisites

• Java 17+
• Docker Desktop (optional but recommended)
• A Telegram bot token created via BotFather

2) Start LibreTranslate + Application with Docker

docker compose up -d --build

3) Run Application Locally Only (PowerShell)

.\gradlew.bat bootRun

For local run, translation service must be available at http://localhost:5000/translate.

---

✅ Test

.\gradlew.bat test --no-daemon

This repo includes a basic Spring context test: WorkRhythmApplicationTests.

---

📮 How to Use the Bot

1. Open your bot in Telegram.
2. Send any message (for example: /start).
3. Bot stores your chatId in chat-ids.txt.
4. You will receive scheduled messages at cron times.

---

🧯 Troubleshooting

Application fails with NumberFormatException

• Cause: chat-ids.txt includes invalid text or too-large numbers.
• Fix: keep only valid numeric chatId values, one per line.

Messages are not delivered

• Verify bot token is correct.
• Make sure you have sent at least one message to the bot.
• Confirm chat-ids.txt is writable.
• Check logs for Telegram bot registered and scheduler trigger messages.

Quote/translation is missing

• ZenQuotes API may be temporarily unavailable.
• If LibreTranslate container is down, translated quote part may be empty.

---

🔐 Security Recommendations

• Provide bot.token via environment variable.
• If token is exposed, rotate it immediately using Telegram BotFather.
• Keep chat-ids.txt protected with proper file permissions in production.

---

License

This project is licensed under the MIT License. See the LICENSE file for details

Created by Mehmet Furkan KAYA