Developer Guide

System Architecture

BitMshauri is built with a modular, scalable architecture designed for reliability and maintainability:

Technology Stack

Prerequisites

• Python 3.8 or higher
• Git
• Telegram Bot Token (from @BotFather)
• OpenAI API Key (optional, for AI features)

Installation Steps

Directory Layout

bitmshauri-bot-3/
├── app/
│   ├── __init__.py
│   ├── enhanced_telegram_bot.py    # Main bot entry point
│   ├── database.py                 # Database models
│   ├── enhanced_database.py        # Enhanced database operations
│   ├── routes.py                   # Web routes (future)
│   └── bot/
│       ├── __init__.py
│       ├── telegram_bot.py         # Core bot functionality
│       ├── price_api.py            # Price fetching
│       ├── content_swahili.py      # Swahili content
│       └── audio_tts.py            # Text-to-speech
├── app/services/
│   ├── calculator.py               # Price calculator
│   ├── community.py                # Group features
│   ├── content_manager.py          # Content management
│   ├── enhanced_audio.py           # Audio processing
│   ├── multi_language.py           # Language handling
│   ├── price_service.py            # Price services
│   └── progress_tracker.py         # User progress
├── app/utils/
│   ├── logger.py                   # Logging utilities
│   └── rate_limiter.py             # Rate limiting
├── docs/                           # Documentation
├── tests/                          # Test suite
├── requirements.txt                # Python dependencies
├── config.py                       # Configuration
├── main.py                         # Alternative entry point
└── setup.py                        # Setup script

Bot Handler

The main bot handler manages incoming messages and routes them to appropriate services:

Service Layer

Database Layer

The database layer provides data persistence and user management:

• User Management: User profiles, preferences, and progress
• Content Storage: Lessons, quizzes, and educational materials
• Community Data: Study groups and group interactions
• Analytics: Usage statistics and learning metrics

Core Tables

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    telegram_id INTEGER UNIQUE NOT NULL,
    username TEXT,
    first_name TEXT,
    last_name TEXT,
    language TEXT DEFAULT 'en',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_active TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    progress_data TEXT,  -- JSON string
    preferences TEXT     -- JSON string
);

CREATE TABLE lessons (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    language TEXT NOT NULL,
    difficulty INTEGER DEFAULT 1,
    category TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE user_progress (
    id INTEGER PRIMARY KEY,
    user_id INTEGER,
    lesson_id INTEGER,
    completed BOOLEAN DEFAULT FALSE,
    score INTEGER,
    completed_at TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (lesson_id) REFERENCES lessons(id)
);

CREATE TABLE study_groups (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    creator_id INTEGER,
    max_members INTEGER DEFAULT 50,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (creator_id) REFERENCES users(id)
);

External APIs

Rate Limiting

The bot implements intelligent rate limiting to prevent abuse:

• User-based limits: Maximum requests per user per time window
• Action-specific limits: Different limits for different commands
• Progressive penalties: Increasing delays for repeated violations
• Whitelist support: Exempt trusted users from limits

Test Suite

Comprehensive testing ensures reliability and quality:

Running Tests

Production Deployment

Deploy the bot to production using various platforms:

Environment Variables

How to Contribute

We welcome contributions from the community! Here's how to get started:

Development Guidelines

• Code Style: Follow PEP 8 Python style guidelines
• Documentation: Add docstrings and update README if needed
• Testing: Write tests for new features
• Commits: Use clear, descriptive commit messages
• Branch Naming: Use descriptive branch names (feature/, bugfix/, etc.)

Areas for Contribution