BotShop

Telegram commerce bot for Indonesian UMKM (small/medium businesses).
Sellers manage their store via Telegram. Buyers browse, ask an AI assistant, and order — all without leaving Telegram.

Stack

Layer	Technology
Language	Java 21 (virtual threads)
Framework	Spring Boot 3.3.5
AI	OpenRouter → stepfun/step-3.5-flash:free via Spring AI
Bot	TelegramBots 6.9 (long-polling dev / webhook prod)
DB	H2 (dev) / PostgreSQL 16 (prod)
Migrations	Flyway
Payments	Xendit
Errors	Sentry

Quick Start (local dev)

# 1. Copy and fill env
cp .env.example .env
# Edit .env — minimum: TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY

# 2. Export env vars
export $(cat .env | grep -v '#' | xargs)

# 3. Run
./mvnw spring-boot:run

H2 console available at http://localhost:8080/h2-console
JDBC URL: jdbc:h2:file:./data/botshop

Production Deploy

# 1. Fill .env.prod
cp .env.example .env.prod

# 2. Build and start
docker compose --env-file .env.prod up -d

# 3. Set up Nginx + SSL
# Edit nginx.conf — replace yourdomain.com
sudo cp nginx.conf /etc/nginx/sites-available/botshop
sudo ln -s /etc/nginx/sites-available/botshop /etc/nginx/sites-enabled/
sudo certbot --nginx -d yourdomain.com
sudo nginx -s reload

Telegram will automatically receive the webhook on startup via SetWebhook.

Project Structure

src/main/java/com/botshop/
├── BotShopApplication.java
├── bot/
│   ├── BotShopBot.java          # Telegram bot, virtual thread dispatch
│   ├── TelegramSender.java      # All outbound messages go here
│   ├── UpdateDispatcher.java    # Routes updates to handlers
│   ├── BotExceptionHandler.java
│   ├── handler/                 # One handler per feature domain
│   │   ├── StartHandler.java
│   │   ├── ShopHandler.java
│   │   ├── CatalogHandler.java
│   │   ├── ProductHandler.java
│   │   ├── OrderHandler.java
│   │   ├── BuyerHandler.java    # Browse + AI Q&A + checkout
│   │   ├── StatsHandler.java
│   │   ├── AiCommandHandler.java
│   │   ├── SubscribeHandler.java
│   │   └── CancelHandler.java
│   └── state/
│       ├── ConversationState.java    # Sealed interface, Java 21
│       └── ConversationStateStore.java
├── config/
│   ├── AppProperties.java       # @ConfigurationProperties
│   ├── OpenRouterConfig.java    # Spring AI ChatClient → OpenRouter
│   └── TelegramConfig.java
├── domain/
│   ├── entity/                  # 9 JPA entities
│   └── repository/              # 7 Spring Data repositories
├── mcp/
│   ├── BotShopMcpTools.java     # 4 @Tool methods for AI
│   └── dto/CatalogSummaryResult.java
├── service/
│   ├── AiService.java           # Q&A + caption + description
│   ├── OrderService.java        # SELECT FOR UPDATE stock decrement
│   ├── SubscriptionService.java
│   ├── UsageService.java        # FUP with 80%/100% warnings
│   ├── UserService.java
│   └── XenditService.java
├── scheduler/
│   └── SubscriptionScheduler.java
└── webhook/
    ├── TelegramWebhookController.java
    └── XenditWebhookController.java

Subscription Plans

Plan	Price	AI Responses/month
Free	—	50
Basic	Rp 29.000	300 + /caption + /description
Pro	Rp 69.000	Unlimited + all features

Bot Commands

/start       — Register or enter a shop via deep link
/shop        — Create / view your shop
/catalog     — Manage product catalogs
/products    — Manage products
/orders      — View and manage orders
/stats       — Monthly stats dashboard
/caption     — AI caption generator (Basic+)
/description — AI product description (Basic+)
/subscribe   — View and upgrade plan
/cancel      — Cancel any active flow

Environment Variables

See .env.example for the full list.