Car Block Telegram Bot

Vibecoded prototype of Spring Boot-based Telegram bot that allows users to communicate with car owners using license plate numbers. Users can register their license plates, send predefined messages, and share contact information with other car owners.

Bot example

@CarBlockBot

Features

• License Plate Registration: Users can register their car license plates linked to their Telegram ID
• Direct Messaging: Send predefined messages to other users by license plate
• Contact Sharing: Share your Telegram username with other car owners
• Plate Management: Register, view, and delete license plates
• Rate Limiting: Prevents spam with configurable message limits (default: 3 messages per hour)
• Database Storage: All data stored in PostgreSQL with Flyway migrations
• User Management: Automatic user creation and profile management

Technology Stack

• Java 17
• Spring Boot 3.2.0
• Spring Data JPA
• PostgreSQL
• Telegram Bot API 6.9.7.1
• Flyway (Database Migrations)
• Maven

Prerequisites

• Docker 20.10 or higher
• Docker Compose 2.0 or higher
• Telegram Bot Token (from @BotFather)

Quick Start with Docker Compose (Recommended)

1. Telegram Bot Setup

1. Start a chat with @BotFather on Telegram
2. Send /newbot command
3. Follow the instructions to create your bot
4. Note down the bot token and username

2. Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env file with your bot token and other preferences
nano .env

Update the .env file with your values:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_BOT_USERNAME=YourBotUsername

3. Start the Application

# Clone the repository
git clone <repository-url>
cd carBlock

# Start all services (builds and runs)
docker-compose up --build

# Or run in background
docker-compose up -d --build

The application will be available with:

• PostgreSQL database automatically created and configured
• Flyway migrations executed automatically
• Bot connected to Telegram and ready to receive messages

4. Stop the Application

docker-compose down

Manual Setup (Alternative)

If you prefer to run without Docker:

Prerequisites

• Java 17 or higher
• PostgreSQL 12 or higher
• Maven 3.6 or higher

Database Setup

Create a PostgreSQL database:

CREATE DATABASE carblock_db;
CREATE USER carblock_admin WITH PASSWORD 'carblock_password';
GRANT ALL PRIVILEGES ON DATABASE carblock_db TO carblock_admin;

Application Configuration

Update src/main/resources/application.properties:

# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/carblock_db
spring.datasource.username=carblock_admin
spring.datasource.password=carblock_password

# Telegram Bot Configuration
telegram.bot.token=YOUR_TELEGRAM_BOT_TOKEN_HERE
telegram.bot.username=YOUR_BOT_USERNAME_HERE

# Rate Limiting Configuration
app.rate-limit.max-messages-per-hour=3
app.rate-limit.window-size-minutes=60

Build and Run

# Build the application
mvn clean install

# Run the application
mvn spring-boot:run

Alternatively, you can run the JAR file directly:

java -jar target/telegram-bot-1.0.0.jar

Bot Commands

Command	Description	Example
/start	Welcome message and introduction	/start
/help	Show all available commands	/help
/register <plate>	Register your license plate	/register ABC123
/plates	View your registered plates	/plates
/delete [number]	Delete a registered license plate	/delete 1
/send <plate>	Send message to plate owner	/send XYZ789
/contact <plate>	Share your contact with plate owner	/contact XYZ789
/status	Check your messaging status	/status

Default Message Templates

The bot comes with 1 predefined message template:

1. "Please move your car, it's blocking my exit."

Additional message templates can be added through the database or by modifying the migration scripts.

Database Schema

The application uses the following main tables:

• users: Stores Telegram user information
• car_plates: Links license plates to users
• message_templates: Predefined message templates
• messages: Stores sent messages
• rate_limits: Tracks user message limits

Rate Limiting

• Users can send a maximum of 3 messages per hour (configurable)
• Rate limit applies to both /send and /contact commands
• Rate limit is per user and resets automatically
• Users can check their remaining messages with /status
• Rate limit window is 60 minutes by default

Configuration Properties

Property	Default	Description
app.rate-limit.max-messages-per-hour	3	Maximum messages per user per hour
app.rate-limit.window-size-minutes	60	Time window for rate limiting
spring.jpa.hibernate.ddl-auto	validate	Hibernate DDL mode
spring.flyway.enabled	true	Enable Flyway migrations
spring.jpa.show-sql	true	Show SQL statements in logs
telegram.bot.token	your_token_here	Telegram bot token
telegram.bot.username	CarBlockBot	Telegram bot username

Development

Running Tests

mvn test

Database Migrations

New migrations should be added to src/main/resources/db/migration/ with the naming convention V{number}__Description.sql.

Adding New Message Templates

You can add new templates either:

1. Via database migration scripts
2. Directly in the database

Add new templates by inserting into the message_templates table:

INSERT INTO message_templates (template_text, description, is_active) 
VALUES ('Your custom message here', 'Template description', true);

Security Considerations

• User Telegram IDs are stored securely in the database
• License plate information is only visible to users who know the plate number
• Contact sharing requires users to have a Telegram username
• Rate limiting prevents spam and abuse
• Input validation prevents SQL injection and other attacks
• Users cannot send messages or contact themselves

Monitoring and Logging

The application includes comprehensive logging:

• DEBUG level for detailed troubleshooting
• INFO level for general operation
• ERROR level for exceptions
• SQL logging enabled for database operations

Logs can be configured in application.properties:

logging.level.com.carblock=DEBUG
logging.level.org.springframework.web=INFO
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

Troubleshooting

Common Issues

1. Bot doesn't respond: Check bot token and internet connection
2. Database connection errors: Verify PostgreSQL is running and credentials are correct
3. Migration failures: Check database permissions and Flyway configuration
4. Contact sharing fails: Ensure you have a Telegram username set in your profile
5. Rate limit exceeded: Wait for the reset time shown in /status command

Health Check

The application exposes Spring Boot Actuator endpoints:

• GET /actuator/health - Application health status
• GET /actuator/info - Application information

Note: Actuator endpoints are available for monitoring but not exposed externally in Docker configuration.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

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

Docker Compose Configuration

Environment Variables

The application can be configured using environment variables in the .env file:

# Database Configuration
DATABASE_URL=jdbc:postgresql://postgres:5432/carblock_db
DATABASE_USERNAME=carblock_admin
DATABASE_PASSWORD=carblock_password

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_BOT_USERNAME=CarBlockBot

# Rate Limiting (Optional)
RATE_LIMIT_MAX_MESSAGES=3
RATE_LIMIT_WINDOW_MINUTES=60

Services

The Docker Compose setup includes two services:

1. postgres: PostgreSQL 15 database

   • Persistent data stored in named volume postgres_data
   • Default credentials: carblock_admin / carblock_password
   • Database: carblock_db

2. carblock-bot: Spring Boot application

   • Built with Maven using multi-stage Docker build
   • Runs on OpenJDK 17 slim runtime
   • Connects to PostgreSQL via internal Docker network
   • Automatically runs Flyway migrations on startup
   • Reads configuration from environment variables

Useful Commands

# View logs
docker-compose logs -f carblock-bot

# View database logs
docker-compose logs -f postgres

# Execute commands in the bot container
docker-compose exec carblock-bot java -version

# Access PostgreSQL database
docker-compose exec postgres psql -U carblock_admin -d carblock_db

# Rebuild only the application
docker-compose up --build carblock-bot

# Remove all data (including database)
docker-compose down -v

Production Considerations

For production deployment:

1. Security:

   • Change default passwords in docker-compose.yml and .env file
   • Use strong, unique passwords
   • Consider using Docker secrets for sensitive data
   • Never commit actual bot tokens to version control

2. Persistence:

   • Database data is persisted in the postgres_data volume
   • Backup the volume regularly: docker run --rm -v postgres_data:/data -v $(pwd):/backup ubuntu tar czf /backup/postgres-backup.tar.gz -C /data .

3. Monitoring:

   • Monitor container health: docker-compose ps
   • Set up log aggregation for production monitoring
   • Configure appropriate log levels for production (INFO instead of DEBUG)

4. Performance:

   • The application uses OpenJDK 17 slim runtime for optimal size
   • Consider resource limits for containers in production

Troubleshooting Docker Issues

1. Build fails:

   • Check Dockerfile syntax
   • Verify Maven dependencies in pom.xml
   • Ensure Java 17 compatibility

2. Database connection errors:

   • Verify PostgreSQL container is running: docker-compose ps
   • Check database logs: docker-compose logs postgres
   • Ensure network connectivity between containers

3. Application won't start:

   • Check application logs: docker-compose logs carblock-bot
   • Verify environment variables are set correctly
   • Ensure Telegram bot token is valid
   • Check if PostgreSQL container is healthy before the bot starts

Support

For issues and questions:

• Create an issue in the GitHub repository
• Check the logs for detailed error information
• Review the troubleshooting section above
• For Docker-specific issues, check container logs with docker-compose logs
• Verify bot commands using /help in the Telegram bot
• Check your rate limit status with /status if messaging fails