🎓 AI Ustaz

AI-powered Telegram Tutor built with Go

An intelligent Telegram bot that helps students solve problems from text, images, and voice messages using Google Gemini and OpenAI Speech-to-Text.

Designed for production deployment with PostgreSQL, Docker, Prometheus, and Railway.

✨ Overview

AI Ustaz is a production-ready educational Telegram bot built to help students learn rather than simply receive answers.

The bot supports multiple input formats, automatically detects the subject of a question, maintains conversation context, and provides detailed explanations generated by AI.

Instead of acting like a chatbot, AI Ustaz behaves as a personal tutor capable of explaining mathematics, physics, chemistry, biology, geography, history, English, and other school subjects.

🚀 Key Features

Feature	Description
🤖 AI Tutor	Step-by-step explanations powered by Google Gemini
💬 Text Questions	Students can ask any question in plain text
🖼 Image Recognition	Solves homework from photos and textbook pages
🎤 Voice Messages	Speech-to-text with OpenAI transcription
🧠 Subject Detection	Automatically identifies the school subject
💭 Conversation Memory	Supports follow-up questions using previous context
📊 Analytics	Tracks users, requests, and activity statistics
👍 Feedback System	Collects Helpful / Not Helpful ratings
🔒 Rate Limiting	Daily request limits per student
🛠 Admin Commands	Built-in monitoring and administration tools
📈 Monitoring	Prometheus metrics and Health Check endpoint
🐳 Production Ready	PostgreSQL, Docker, Railway deployment

📸 Demo

💬 Text Question

Students can send ordinary text questions and receive detailed explanations.

🖼 Image Question

Homework, textbook pages, handwritten notes, and mathematical problems can be analyzed directly from images.

🎤 Voice Question

Voice messages are automatically transcribed using OpenAI and then processed by Gemini.

👤 User Profile

Each student has a profile containing request statistics and daily limits.

📊 Bot Statistics

Administrators can monitor overall bot usage and feedback.

🎯 Engineering Highlights

Production-ready Go backend
Modular architecture
AI provider abstraction
Conversation history
Subject-aware prompting
Daily rate limiting
PostgreSQL persistence
Structured logging
Prometheus metrics
Health checks
Graceful shutdown
Docker deployment

🏗 Architecture

flowchart TD

User["👨‍🎓 Student"]

Telegram["Telegram Bot API"]

Handler["Telegram Handler"]

Tutor["Tutor Service"]

Classifier["Subject Detection"]

History["Conversation History"]

Limiter["Rate Limiter"]

Gemini["Google Gemini"]

OpenAI["OpenAI Speech-to-Text"]

Stats["Statistics"]

Postgres["PostgreSQL"]

Metrics["Prometheus"]

User --> Telegram

Telegram --> Handler

Handler --> Tutor

Tutor --> Classifier

Tutor --> History

Tutor --> Limiter

Tutor --> Stats

Tutor --> Gemini

Tutor --> OpenAI

History --> Postgres

Limiter --> Postgres

Stats --> Postgres

Tutor --> Metrics

The project follows a modular architecture where each package has a single responsibility.

The Telegram layer is responsible only for communication with Telegram.

Business logic is implemented inside services.

Infrastructure concerns such as AI providers, storage, statistics, metrics, and rate limiting are isolated behind interfaces.

This allows replacing implementations without changing business logic.

📂 Project Structure

cmd/
├── bot/                # Application entrypoint
└── migrate/            # Database migrations

internal/
├── access/             # User access management
├── ai/                 # Gemini & OpenAI clients
├── app/                # Dependency initialization
├── config/             # Environment configuration
├── db/                 # PostgreSQL connection
├── entity/             # Domain models
├── httpserver/         # Health server
├── limiter/            # Daily request limits
├── metrics/            # Prometheus metrics
├── migrations/         # Embedded SQL migrations
├── service/            # Business logic
├── stats/              # Analytics
├── storage/            # Conversation history
└── telegram/           # Telegram handlers

pkg/
└── logger/

docs/
└── screenshots/

Dockerfile
docker-compose.yml
Makefile
README.md

🛠 Tech Stack

Backend

Go
REST API
Clean Architecture
Dependency Injection
Graceful Shutdown

Artificial Intelligence

Google Gemini 2.5 Flash
OpenAI Speech-to-Text
Prompt Engineering
Subject-specific prompting

Database

PostgreSQL
pgx
Goose Migrations

Infrastructure

Docker
Docker Compose
Railway

Monitoring

Prometheus
Health Check Endpoint
Structured Logging

Telegram

go-telegram-bot-api
Long Polling
Voice Messages
Image Processing
Markdown Responses

⚡ Core Functionality

AI Pipeline

Voice
    │
    ▼
OpenAI Transcription
    │
    ▼
Subject Detection
    │
    ▼
Conversation Context
    │
    ▼
Google Gemini
    │
    ▼
Formatted Answer

Supported Subjects

Mathematics
Physics
Chemistry
Biology
English
History
Geography
General Questions

🔑 Main Components

Component	Responsibility
Telegram	User interaction
Tutor Service	Business logic
Gemini Client	AI responses
OpenAI Client	Voice transcription
Storage	Conversation history
Statistics	User analytics
Limiter	Daily request limits
Metrics	Prometheus monitoring
HTTP Server	Health endpoint
PostgreSQL	Persistent storage

📊 Production Features

✅ PostgreSQL persistence
✅ Embedded SQL migrations
✅ Conversation memory
✅ Subject-aware prompting
✅ Request analytics
✅ Feedback collection
✅ Prometheus metrics
✅ Health endpoint
✅ Structured logging
✅ Docker deployment
✅ Railway deployment
✅ Graceful shutdown

🚀 Getting Started

Prerequisites

Go 1.24+
PostgreSQL 15+
Docker (optional)
Google Gemini API Key
OpenAI API Key
Telegram Bot Token

⚙ Configuration

Create a .env file:

APP_ENV=local

HTTP_PORT=8082

DATABASE_URL=postgres://postgres:password@localhost:5432/aiustaz?sslmode=disable

TELEGRAM_BOT_TOKEN=

ADMIN_TELEGRAM_ID=

AI_PROVIDER=gemini

GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.5-flash

OPENAI_API_KEY=
OPENAI_TRANSCRIBE_MODEL=gpt-4o-mini-transcribe

🐳 Run with Docker

Start PostgreSQL

docker compose up -d

Run migrations

make migrate

Start the bot

make run

💻 Local Development

Install dependencies

go mod download

Run migrations

go run ./cmd/migrate

Start bot

go run ./cmd/bot

📋 Available Commands

User Commands

Command	Description
/start	Register user
/help	Show help
/profile	User profile
/limit	Remaining daily requests
/reset	Clear conversation history

Admin Commands

Command	Description
/stats	Bot statistics

❤️ Health Check

GET /health

Example response

{
    "status":"ok",
    "database":"connected",
    "version":"1.0.0"
}

📈 Metrics

Prometheus endpoint

GET /metrics

Example metrics

telegram_requests_total

telegram_users_total

telegram_feedback_total

telegram_ai_requests_total

telegram_errors_total

🔒 Security

The project follows several production practices:

Environment variables for secrets
PostgreSQL parameterized queries
Daily request rate limiting
Graceful shutdown
Structured logging
Health monitoring
Conversation history isolation

⚡ Performance

Production optimizations include:

PostgreSQL connection pooling
Embedded SQL migrations
Reusable AI client
Modular services
Lightweight HTTP server
Memory-efficient handlers
Split long Telegram messages
Markdown sanitization

🧪 Testing

Run all tests

go test ./...

Run with coverage

go test ./... -cover

🚢 Deployment

The application is designed for cloud deployment.

Tested with:

Railway
Docker
PostgreSQL
Prometheus

Deployment flow

GitHub

↓

Railway

↓

Docker Container

↓

PostgreSQL

↓

Telegram Bot

🔄 CI/CD Ready

The project structure supports future integration with:

GitHub Actions
Docker Hub
Railway Deployments
Kubernetes

🗺 Roadmap

Completed

Planned

💡 Engineering Challenges

During development several engineering problems had to be solved.

Multi-modal AI

The bot supports three completely different input types:

Text
Images
Voice messages

Each follows a different processing pipeline before reaching the AI model.

Subject-aware prompting

Instead of using a single generic prompt, the bot first classifies the subject (Mathematics, Physics, Biology, etc.) and then applies specialized prompts to improve answer quality.

Telegram limitations

Telegram imposes several constraints:

Maximum message length
Markdown parsing
File uploads
Voice message handling

The project implements dedicated utilities to safely format and split long responses.

Production deployment

The application was designed to run continuously in production using:

Docker
Railway
PostgreSQL
Prometheus

with health checks and graceful shutdown support.

📚 Lessons Learned

Building AI Ustaz significantly improved my knowledge in:

Go application architecture
Modular project organization
PostgreSQL schema design
Telegram Bot API
AI prompt engineering
Google Gemini integration
OpenAI Speech-to-Text
Docker deployment
Monitoring with Prometheus
Production logging
Environment configuration
Dependency management

🤝 Contributing

Contributions, ideas, bug reports, and feature requests are welcome.

Feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Bekzat Tursun

Backend Software Engineer

GitHub

https://github.com/cobrich

https://linkedin.com/in/tursunbekzat

Email

tursunbekzat07@gmail.com

⭐ If you found this project interesting, consider giving it a star.

Built with ❤️ using Go, Google Gemini and OpenAI.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
cmd		cmd
docs		docs
internal		internal
pkg/logger		pkg/logger
utils		utils
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

🎓 AI Ustaz

AI-powered Telegram Tutor built with Go

✨ Overview

🚀 Key Features

📸 Demo

💬 Text Question

🖼 Image Question

🎤 Voice Question

👤 User Profile

📊 Bot Statistics

🎯 Engineering Highlights

🏗 Architecture

📂 Project Structure

🛠 Tech Stack

Backend

Artificial Intelligence

Database

Infrastructure

Monitoring

Telegram

⚡ Core Functionality

AI Pipeline

Supported Subjects

🔑 Main Components

📊 Production Features

🚀 Getting Started

Prerequisites

⚙ Configuration

🐳 Run with Docker

💻 Local Development

📋 Available Commands

User Commands

Admin Commands

❤️ Health Check

📈 Metrics

🔒 Security

⚡ Performance

🧪 Testing

🚢 Deployment

🔄 CI/CD Ready

🗺 Roadmap

Completed

Planned

💡 Engineering Challenges

Multi-modal AI

Subject-aware prompting

Telegram limitations

Production deployment

📚 Lessons Learned

🤝 Contributing

📄 License

👨‍💻 Author

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages