Ballkit

Ballkit is a platform for launching digital loyalty programs for small and medium-sized businesses in just 15 minutes without technical knowledge or complex integrations.

Features

• Loyalty mechanics
  Accumulate and redeem bonus points for purchases.

• User roles

  • Business owner manages stores and tracks statistics.
  • Store administrator manages employees and transactions.
  • Seller accrues and redeems bonuses.
  • Customer participates via Telegram bot.

• Admin action logging
  All administrative operations are stored in a dedicated database table.

• Telegram as frontend
  Customers interact with the program through a familiar Telegram interface.

• Website integration
  Tilda widget allows embedding the loyalty program directly into the site.

• Fast performance
  Redis cache on top of PostgreSQL reduces client-server latency by 4x.

• High load support
  Platform sustains 1000 RPS. Run the load test with:

  go run ./cmd/loadtest

Architecture

• Telegram Bot — main frontend for customers and sellers, communicates with backend via gRPC.
• Tilda Widget — JavaScript widget for websites, communicates via HTTP/WebHook wrapping gRPC methods.
• Backend — GoLang service, PostgreSQL as source-of-truth, Redis as cache.
• Sync module — asynchronous system keeps PostgreSQL and Redis in sync.

System diagram:

[ Client (Telegram) ] <---> [ Telegram Bot ] <--gRPC--> [ Backend ] <---> [ Postgres ]
                                                          │
                                                          └--> [ Redis ] (cache)

[ Website (Tilda) ] <---> [ JS Widget ] <--HTTP/WebHook--> [ Backend ]

Database schema

Deployment and usage

Production

git pull
docker compose up --build -f compose.prod.yaml

Prepay deployment

chmod +x init.sh
. init.sh

Development

1. Forward localhost:8080 to HTTPS with ngrok:

   ngrok http 8080

2. Set webhook:

   curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=<NGROK_HTTPS_URL>/webhook"

3. Run bot:

   go run cmd/main.go

TransactionFSM

State machine for bot operation:

stateDiagram-v2
    [*] --> start_of_transaction
    auth_success --> wait_for_check_amount: ask_check_amount
    start_of_transaction --> waiting_customer_mobile: ask_customer_mobile
    start_of_transaction --> waiting_qr_scanning: scan_customer_qr
    transaction_finished --> end_of_transaction: end_transaction
    wait_detruct_bonus_count --> transaction_finished: finsh_transaction
    wait_earn_bonus_count --> transaction_finished: finsh_transaction
    wait_for_check_amount --> wait_detruct_bonus_count: detruct_bonus
    wait_for_check_amount --> wait_earn_bonus_count: earn_bonus
    waiting_confirm_code --> auth_success: copmlete_authorization
    waiting_customer_mobile --> waiting_confirm_code: ask_confirm_code
    waiting_qr_scanning --> auth_success: copmlete_authorization

Loading

To regenerate diagram:

cd bot && go run cmd/bot/main.go --fsm-visualize

Production webhook

Use https://<youdomain>/webhook instead of ngrok URL.

License

MIT License