Yaltopia-Homes-TGClient/README.md

🏠 Yaltipia Telegram Bot

A powerful, production-ready Telegram bot for real estate property notifications. Users can create custom property alerts and receive instant notifications when matching properties become available.

🚀 Features

🔔 Smart Notifications

• Custom Property Alerts - Users set criteria (type, location, price range)
• Automatic Matching - Bot finds properties matching user preferences
• Real-time Notifications - Instant alerts via Telegram (with webhook support)
• Flexible Filtering - By property type, location, house type, and price

👤 User Management

• Secure Authentication - Phone-based registration and login
• Session Management - Persistent user sessions with token-based auth
• Notification Management - Create, view, edit, and delete notifications
• User-friendly Interface - Intuitive inline keyboards and menus

📊 Admin Monitoring

• Real-time Health Monitoring - System health checks every 30 minutes
• Error Reporting - Automatic error alerts to admin chat
• Failed Login Tracking - Security alerts for failed authentication attempts
• Daily Reports - Comprehensive system statistics
• Performance Metrics - Memory usage, uptime, and error rates

🔒 Security & Performance

• Rate Limiting - Protection against spam and abuse
• Input Validation - Secure handling of user inputs
• Error Handling - Comprehensive error management
• Security Headers - Protection against common web attacks
• Production Hardening - Security best practices implemented

📋 Quick Start

Prerequisites

• Node.js 16+ and npm
• Telegram Bot Token (from @BotFather)
• Backend API for property data
• Admin Telegram chat for monitoring

Installation

# Clone the repository
git clone <your-repository-url>
cd yaltipia-telegram-bot

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Configure your environment variables
nano .env

Configuration

Edit .env with your settings:

# Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
API_BASE_URL=https://your-api.com/api
WEBSITE_URL=https://yaltipia.com

# Notification System
NOTIFICATION_MODE=optimized
NOTIFICATION_CHECK_INTERVAL_HOURS=6
SEND_NO_MATCH_NOTIFICATIONS=false

# Admin Monitoring
ADMIN_CHAT_IDS=your_admin_chat_id
MONITORING_TOPIC_ID=your_topic_id

Start the Bot

# Development
npm run dev

# Production
npm start

# With PM2 (recommended for production)
pm2 start src/bot.js --name "yaltipia-bot"

🏗️ Architecture

System Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Telegram      │    │   Yaltipia Bot   │    │   Backend API   │
│   Users         │◄──►│                  │◄──►│   (Property     │
│                 │    │   • Auth         │    │    Data)        │
└─────────────────┘    │   • Notifications│    └─────────────────┘
                       │   • Monitoring   │              │
┌─────────────────┐    │   • Webhooks     │              │
│   Admin Chat    │◄───┤                  │              │
│   (Monitoring)  │    └──────────────────┘              │
└─────────────────┘             │                        │
                                │                        │
                       ┌──────────────────┐              │
                       │   Webhook Server │◄─────────────┘
                       │   (Real-time)    │
                       └──────────────────┘

Notification Modes

Mode	Description	Use Case
optimized	Polls API every 6 hours	Current setup (no backend changes needed)
full	Real-time webhooks + polling backup	Future upgrade (requires backend integration)

📖 User Guide

For End Users

1. Start the bot: Send /start to the bot
2. Register/Login: Provide phone number and password
3. Create notifications: Use "🔔 Create Notification" button
4. Set preferences: Choose property type, location, price range
5. Receive alerts: Get notified when matching properties are found

Supported Property Criteria

• Property Type: Rent, Sale
• Location: Any subcity (Bole, Kirkos, Addis Ketema, etc.)
• House Type: Apartment, Villa, Studio, Condominium, etc.
• Price Range: Minimum and maximum price limits

🛠️ Development

Project Structure

yaltipia-telegram-bot/
├── src/
│   ├── bot.js                 # Main bot application
│   ├── api.js                 # Backend API client
│   ├── features/              # Bot features (auth, notifications, menu)
│   ├── services/              # Notification services
│   ├── utils/                 # Utilities (monitoring, error handling)
│   └── webhook/               # Webhook handlers
├── scripts/                   # Utility scripts
├── docs/                      # Documentation
├── .env.example              # Environment template
└── package.json              # Dependencies and scripts

Available Scripts

npm run dev          # Start in development mode with nodemon
npm start            # Start in production mode
npm test             # Run tests (if available)

Environment Variables

Variable	Description	Default
TELEGRAM_BOT_TOKEN	Bot token from BotFather	Required
API_BASE_URL	Backend API endpoint	Required
NOTIFICATION_MODE	Notification system mode	optimized
NOTIFICATION_CHECK_INTERVAL_HOURS	Check frequency	6
ADMIN_CHAT_IDS	Admin chat IDs (comma-separated)	Required
HEALTH_CHECK_INTERVAL_MINUTES	Health check frequency	30

🚀 Deployment

Quick Deployment

For detailed deployment instructions, see SECURITY_DEPLOYMENT_CHECKLIST.md

# 1. Server setup
sudo npm install -g pm2

# 2. Clone and install
git clone <repo> && cd yaltipia-telegram-bot
npm ci --only=production

# 3. Configure environment
cp .env.production .env
# Edit .env with production values

# 4. Start application
pm2 start src/bot.js --name "yaltipia-bot"
pm2 save && pm2 startup

Docker Deployment

# Build image
docker build -t yaltipia-bot .

# Run container
docker run -d \
  --name yaltipia-bot \
  --env-file .env.production \
  -p 3001:3001 \
  yaltipia-bot

Health Checks

Endpoint	Purpose
GET /status	Application health status
GET /webhook/health	Webhook service health

📊 Monitoring

Built-in Monitoring Features

• System Health: Memory usage, error rates, uptime tracking
• User Activity: Login attempts, notification creation, message processing
• Error Tracking: Automatic error reporting with stack traces
• Performance Metrics: Response times, API call success rates

Admin Notifications

The bot automatically sends alerts to admin chat for:

• 🚨 Critical system issues (high error rates, memory problems)
• 🔐 Security events (failed login attempts, suspicious activity)
• 📊 Daily reports (system statistics and health summary)
• ⚠️ Application errors (with detailed error information)

🔗 Webhook Integration

Current Setup

• Mode: Optimized polling (checks every 6 hours)
• Backend Required: No webhook integration needed

Future Enhancement

• Mode: Real-time webhooks (instant notifications)
• Backend Required: Send HTTP POST to bot when properties are added/updated

For webhook integration guide, see docs/WEBHOOK_INTEGRATION_GUIDE.md

🔒 Security

Security Features

• ✅ Rate limiting (100 requests/minute per IP)
• ✅ Input validation and sanitization
• ✅ Secure authentication with token management
• ✅ Error handling without information leakage
• ✅ Security headers for webhook endpoints
• ✅ Environment variable protection

Security Best Practices

• Never commit .env files to version control
• Use strong, unique bot tokens for production
• Regularly rotate authentication tokens
• Monitor admin chat for security alerts
• Keep dependencies updated

📚 Documentation

Document	Description
SECURITY_DEPLOYMENT_CHECKLIST.md	Complete deployment guide for DevOps teams
docs/WEBHOOK_INTEGRATION_GUIDE.md	Future webhook integration instructions
docs/CONFIGURATION_GUIDE.md	Detailed configuration options
docs/MONITORING_SYSTEM.md	Monitoring and alerting setup

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style and patterns
• Add appropriate error handling
• Update documentation for new features
• Test thoroughly before submitting PR

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Getting Help

• 📖 Check the documentation first
• 🐛 Report bugs via GitHub Issues
• 💬 Contact the development team
• 📧 Email: [your-support-email]

Common Issues

• Bot not responding: Check bot token and network connectivity
• API errors: Verify API_BASE_URL and backend availability
• No notifications: Ensure users are logged in and have active notifications
• Memory issues: Monitor system resources and restart if needed

🎯 Roadmap

Current Version (v1.0)

• ✅ Basic notification system with polling
• ✅ User authentication and management
• ✅ Admin monitoring and alerts
• ✅ Security hardening

Future Enhancements

• 🔄 Real-time webhooks (when backend supports it)
• 📱 Mobile app integration
• 🔍 Advanced search filters
• 📊 Analytics dashboard
• 🌐 Multi-language support

---

🏆 Production Ready

This bot is production-ready with:

• ✅ Comprehensive security measures
• ✅ Robust error handling and monitoring
• ✅ Scalable architecture design
• ✅ Complete documentation for deployment
• ✅ DevOps-friendly configuration

Deploy with confidence! 🚀

---

Built with ❤️ for Yaltipia

🏠 Website • 📱 Telegram Bot • 📧 Support