prayer-bot 🙏

A serverless Telegram bot that provides Muslim prayer times and sends notifications when prayers are approaching.

Currently Available Cities

City	Bot
Kazan	@kazan_prayer_bot
Innopolis	@innopolis_prayer_bot

---

Architecture 🏗️

The bot runs on GCP Cloud Functions with Supabase Postgres for data and GCS for prayer schedule CSV files.

flowchart LR
  Telegram --> Dispatcher
  Scheduler --> Reminder
  GCS --> Loader

  Dispatcher --> Postgres[(Supabase Postgres)]
  Reminder --> Postgres
  Loader --> Postgres
  Loader --> GCS

Loading

Infrastructure is defined in infra/gcp/.

Deployment

GitHub secrets (per environment):

Secret	Purpose
APP_CONFIG	Bot config JSON
GCP_PROJECT_ID	GCP project ID
GCP_SA_KEY	GCP deploy service account JSON
GCP_TFSTATE_BUCKET	GCS bucket for Terraform state
SUPABASE_DB_URL	Supabase transaction pooler URL (port 6543) — runtime DATABASE_URL on functions
SUPABASE_DB_DIRECT_URL	Supabase direct Postgres URL (port 5432) — Goose schema migrations

Automatic deploys

Trigger	Environment	What runs
Pull request → main	dev	lint → validate → plan → Goose migrate → Terraform apply → webhooks → profiles
Push / merge to main	prod	same full chain

Manual deploy (hotfixes): Actions → Deploy to GCP → Run workflow → pick dev or prod and optionally a branch.

---

Configuration 🛠️

Bot configuration is managed through environment variables.

Below is an example of an APP_CONFIG value containing all bot information:

{
  "648252": {
    "bot_id": 648252,          // Bot ID
    "owner_id": 1385434843,    // Bot owner ID
    "location": "Europe/Moscow", // Timezone of the city
    "token": "oa7GmLW3fncbOE0MTfV0mKxH/F37cShhxgZ1mjl614w", // Telegram token
    "secret": "Noe&uPcwjaAxjqJU_JP4C^g2V7ZDQX" // Secret key to verify requests
  },
  ...
}

• To find your owner ID, use ID bot
• Bot ID is the first number before : in the bot token
  • TOKEN: 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
  • Bot ID: 123456789

---

Bot Features 🤖

User Commands 📝

Command	Description
today	Get today's prayer times
date	Get prayer times for a specific date
next	Find out the next prayer time
subscribe	Subscribe to daily reminders
unsubscribe	Unsubscribe from daily reminders
remind	Set reminder offset for the next prayer
language	Change the bot language
help	Show help message
bug	Report a problem to bot owner
feedback	Send feedback to bot owner

Admin Commands 📝

Command	Description
admin	Show admin help message
stats	View bot usage statistics
announce	Send message to all users
reply	Reply to user's bug/feedback message

---

References 📚

• go-telegram
• telegram-api

---

How to Contribute 🤝

[1] Add a City

You do:

1. Get prayer times for a city in CSV format
2. Make a pull request (or open an issue) with the new file

I do:

1. Create a new Telegram bot
2. Upload the city file to the GCS data bucket

[2] Add a Language

You do:

1. Create translation text for the following files:
   • ./serverless/reminder/internal/handler/languages/text.yaml
   • ./serverless/dispatcher/internal/handler/languages/en.yaml (replace en with the new language code)

I do:

1. Deploy a new version of the code

[3] Code Contributions

Found a bug? Want to add a new feature? Just open an issue or submit a pull request.

---

Development Roadmap 🚀

V1 ✅

• Support date format for /prayersdate command with leading zeros and delimiters (. / -)
• Implement subscriptions & notifications
• Update text messages to be more user-friendly

V2 ✅

• Store prayer times in memory to reduce database requests
• Add response endpoint for admin to address feedback & bug messages
• Add Jumu'ah prayer reminders on Fridays

V3 ✅

• Add time keyboard to /date command
• Remove selection message for /date & /lang after user interaction or timeout
• Terminate other active channels when user sends new commands
• Add feature to delete old prayer time message when a new one is sent
• Enable admins to broadcast messages to all subscribers
• Add feature to get subscriber count for admins
• Write more robust tests for core features

V4 ✅

• Add multi-language support (AR, RU, TT, TR, UZ)
• Implement script messages in the bot
• Set user script before command if not set
• Use script commands in notifications
• Fix prayer timetables for other languages

V5 ✅

• Refactor code for better readability and maintainability
• Enhance logging to be more informative
• Enable using multiple bots with the same codebase

V6 ✅

• Migrate to serverless architecture
• Automate deployment using Terraform
• Add support for multiple cities
• Add Spanish & French language support
• Add /stats command for bot usage statistics

V7 ✅

• Add jamaat gathering feature for group chats

V8 🔄

• Add support for all major world cities

---

Visualization 🖥️

cd infra/gcp
terraform plan -out plan.out
terraform show -json plan.out > plan.json
docker run --rm -it -p 9000:9000 -v "$(pwd)/plan.json:/src/plan.json" im2nguyen/rover:latest -planJSONPath=plan.json