Solo Leveling

🔗 View on GitHub

A Spring Boot–based Telegram bot that helps users track daily activities, monitor discipline, and generate performance reports in PDF format using JasperReports.
It gamifies self-improvement — users gain levels, rankings, and consistency scores through daily #report messages.

🚀 Features¶

/start registration — auto-creates a new user record in PostgreSQL.
Daily activity tracking with hashtags (#report).
Personalized motivational quotes (random from 30+ proverbs).
PDF reports (weekly, monthly, annual, custom) generated with JasperReports.
Dynamic buttons and inline menu navigation.
Top-100 leaderboard ranked by level.
Profile view with user rank, level, and subscription info.
Data persistence with JPA/Hibernate + PostgreSQL.
Secure configuration via .env file.

🧩 Architecture Overview¶

Core Flow¶

Telegram Update → TelegramBotService
Receives user input and creates an UpdateContext (chatId, username, text).
Command Dispatch
Iterates through all CommandHandler beans; executes the first matching one.
Business Logic Layer (Service)
Reads/writes entities using repositories.
Presentation Layer
Messages, buttons, and media are sent back to the user using MessageSender.

🧱 Design Patterns Used¶

Pattern	Location	Purpose
Command Pattern	`bot.command.*`	Each bot command (e.g., `/start`, “Profile👤”) is encapsulated in its own class implementing `CommandHandler`.
Dependency Injection (IoC)	Spring Boot `@Component`, `@Service`, `@Autowired`	Promotes testability and modularity.
Repository Pattern	`UserRepository`, `UserReportsRepository`	Separates persistence logic from domain logic.
Strategy Pattern (Implicit)	Multiple command handlers implementing `supports()` and `handle()` — dynamically selected at runtime.
Builder / Template Pattern (JasperReports)	In `ReportingService` and `PeriodReportCommand` for PDF generation templates.
Singleton (Spring-managed beans)	Services, repositories, and configs are singletons managed by Spring container.

⚙️ Tech Stack & Dependencies¶

Languages & Frameworks - Java 23 - Spring Boot 3.5.7 - Spring Data JPA (Hibernate) - Telegram Bots Java SDK - JasperReports - PostgreSQL

Libraries

Dependency	Purpose
`org.springframework.boot:spring-boot-starter-web`	Core web + REST + DI
`org.springframework.boot:spring-boot-starter-data-jpa`	ORM / Hibernate
`org.postgresql:postgresql`	JDBC driver
`org.telegram:telegrambots-spring-boot-starter`	Telegram API
`net.sf.jasperreports:jasperreports`	PDF report rendering
`io.github.cdimascio:java-dotenv`	Environment variable loading
`jakarta.persistence`, `jakarta.annotation`	JPA and lifecycle annotations

🧰 Project Structure (Modules)¶

Package	Description
`bot.command`	Contains all user-facing commands (e.g., `/start`, `Profile👤`, `Analyze & Report📉`).
`bot.model`	Defines `UpdateContext` — normalized Telegram update info.
`bot`	Core I/O: `MessageSender` (sends messages, PDFs, videos), `ButtonsManager` (keyboards), `TelegramBotService` (dispatcher).
`service`	Contains all business logic: user management, PDF generation, report aggregation.
`repository`	JPA repositories for database operations.
`domain`	Entity layer (`User`, `UserReports`, `Activity`).
`util`	Utility classes (motivational `Proverb`).
`config`	Spring Beans configuration and Telegram bot credentials.

🔐 Environment Variables¶

This project uses dotenv (.env file) for sensitive data.
Create .env in the root directory:

TELEGRAM_BOT_USERNAME=Solo_Progression_bot
TELEGRAM_BOT_TOKEN=your_token_here

DB_URL=jdbc:postgresql://localhost:5435/mydb
DB_USERNAME=postgres
DB_PASSWORD=password

In application.properties, these env vars are loaded dynamically:

telegram.bot.username=${TELEGRAM_BOT_USERNAME}
telegram.bot.token=${TELEGRAM_BOT_TOKEN}
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

Telgram Bot Commands¶

Command / Button	Description
`/start`	Registers a new user, sends intro video & motivational quote.
`Profile👤`	Displays user's stats (level, rank, subscription).
`Instruction⚙️`	Sends a video (`HowToUse.mp4`) + format guide for `#report`.
`Analyze & Report📉`	Opens submenu to choose report type (weekly, monthly, annual).
`Weekly report📊`, `Monthly Report📊`, `Annual report📊`, `Until now📊`	Generates PDF report and summary stats.
`Ranking🏆`	Displays top players sorted by level.
`Back◀️`	Returns to main menu.
`#report`	Users send activity report in the format:

Example Input:

#report
Sport,20,50
Study,120,80

...

🧾 PDF Reporting¶

Generated via JasperReports using solo.jrxml template.

Each PDF includes: - User’s name and date range - Activity list with total hours & average consistency - Overall score summary - graphs and charts

The report is sent as a Telegram document attachment using:

sender.sendPdf(chatId, pdfBytes, "<b>From " + startDate + " to " + LocalDate.now() + "</b>");

🧪 Running Locally¶

1️⃣ Prerequisites

Java 17+
Maven or Gradle
PostgreSQL running locally

3️⃣ Create .env

TELEGRAM_BOT_USERNAME=Solo_Progression_bot
TELEGRAM_BOT_TOKEN=123456:ABC...
DB_URL=jdbc:hostname
DB_USERNAME=postgres
DB_PASSWORD=password

4️⃣ Run Application

mvn spring-boot:run
java -jar target/soloLeveling-0.0.1-SNAPSHOT.jar

🌱 Future Improvements¶

💳 Add subscription payment integration (Stripe or Telegram Payments API). Used as a penalty for low consistency.

⏰ Add daily reminders using Telegram Scheduled Messages.

⚡ Optimize ranking queries with caching (Redis).

🌍 Add multilingual support (English / Uzbek / Russian).