A comprehensive, secure attendance tracking system built with Python and Telegram Bot API. Features location-only check-ins, exceptional hours management, real-time admin reporting, and a modern web dashboard.
- Location-only attendance - Manual GPS entry completely disabled
- 100m radius enforcement - Must be within office proximity
- Real-time verification - GPS coordinates validated instantly
- Secure conversation state - Multi-step interactions protected
- Simple check-in/out via location sharing buttons
- Automatic late detection with reason prompts
- Early departure handling with mandatory explanations
- Personal status tracking and attendance reports
- Exceptional hours awareness for custom schedules
- Daily summary reports automatically sent at 8 PM
- Real-time dashboards with attendance statistics
- Web-based admin panel with charts and analytics
- Exceptional hours management for individual employees
- Enhanced late alerts with employee-provided reasons
- Employee directory with comprehensive management
- Server health monitoring and activity logging
- Modern web interface with responsive design
- Real-time analytics and attendance charts
- Employee management with admin controls
- Report generation and CSV exports
- Interactive dashboards with live data
- Settings management and configuration
- Dual deployment modes - Bot only or Bot + Web interface
- Server wake-up system (prevents Render free tier sleep)
- Comprehensive logging and error handling
- Database optimization with proper indexing
- Graceful shutdown handling
- Modular architecture for easy maintenance
- Python 3.8+
- Telegram Bot Token
- Internet connection for API calls
-
Clone and setup:
git clone <repository-url> cd "Mansoura CIH Telegram Attendance System" pip install -r requirements.txt
-
Configure environment:
cp .env.template .env # Edit .env with your bot token and settings -
Run the system:
Option A: Complete System (Bot + Web Interface)
python app.py # Access web dashboard at: http://localhost:5000Option B: Telegram Bot Only
python run_bot.py
Option C: Web Interface Only
python run_web.py
- URL:
http://localhost:5000(or your deployed domain) - Admin Login:
/login - Default Credentials:
- Username:
admin - Password:
mansoura2024
- Username:
- Dashboard: Real-time attendance overview
- Employee Management: View, edit, and manage employees
- Reports: Generate and export attendance reports
- Analytics: Charts and statistics
- Settings: System configuration
Add to your .env file:
# Web Interface
WEB_SECRET_KEY=your-secret-key-here
WEB_ADMIN_USER=admin
WEB_ADMIN_PASS=your-secure-password
FLASK_DEBUG=falseattendance_system/
├── core/
│ ├── config.py # Configuration management
│ ├── database.py # Database operations
│ └── __init__.py
├── handlers/
│ ├── employee.py # Employee command handlers
│ ├── admin.py # Admin command handlers
│ └── __init__.py
├── services/
│ ├── notification.py # Notification scheduling
│ ├── health.py # Health monitoring
│ └── __init__.py
├── utils/
│ ├── location.py # Location validation
│ ├── keyboards.py # Telegram keyboards
│ ├── messages.py # Message formatting
│ └── __init__.py
├── main.py # Application entry point
└── __init__.py
requirements.txt # Dependencies
run.py # Launcher script
.env # Environment configuration
Create a .env file with the following settings:
# Bot Configuration
BOT_TOKEN=your_telegram_bot_token_here
# Office Location (29R3+7Q El Mansoura 1)
OFFICE_LATITUDE=31.0417
OFFICE_LONGITUDE=31.3778
OFFICE_RADIUS=100
OFFICE_ADDRESS=29R3+7Q El Mansoura 1
# Work Hours
DEFAULT_WORK_START=09:00
DEFAULT_WORK_END=17:00
# Server Configuration
PORT=8080
SERVER_URL=http://localhost:8080
# Security
LOCATION_ONLY_ATTENDANCE=true
MANUAL_ENTRY_DISABLED=true
# Development
DEBUG=false
LOG_LEVEL=INFOThe system uses SQLite with the following main tables:
- employees - Employee registration and settings
- attendance - Daily check-in/out records with reasons
- admins - Administrator permissions and settings
- exceptional_hours - Custom work schedules
- conversation_state - Multi-step interaction handling
- notification_log - Sent message tracking
- server_activity - System monitoring logs
/start- Welcome message and main keyboard/register- Register as new employee/status- View today's attendance status/report- View recent attendance history/help- Comprehensive help information/myid- Get Telegram user ID
/admin- Main admin control panel/add_admin <user_id>- Grant admin privileges/exceptional_hours <user_id> <date> <start> <end> [reason]- Set custom hours/admin_report- Real-time attendance dashboard/list_employees- Employee directory/server_status- System health and activity logs
- All check-ins/outs require location sharing
- Manual GPS entry is completely disabled
- Distance verification with configurable radius
- Real-time coordinate validation
- Role-based access control
- Admin actions logged with timestamps
- Secure conversation state management
- Input validation and sanitization
- Sensitive data encryption at rest
- Comprehensive audit logging
- Automatic data cleanup routines
- Error handling without data exposure
Automatically sent to all admins at 8 PM with:
- Total employees and attendance counts
- Late arrivals with reasons
- Early departures with explanations
- Attendance rate calculations
- Current day attendance overview
- Employee status monitoring
- Quick action buttons for common tasks
- Interactive employee management
- Set custom work schedules for specific dates
- Override standard work hours
- Reason tracking and audit trails
- Bulk operations support
- Modular architecture with clear separation of concerns
- Type hints throughout for better code maintainability
- Comprehensive logging for debugging and monitoring
- Error handling with graceful degradation
- Database abstraction for easy testing and migration
# Install development dependencies
pip install pytest pytest-asyncio
# Run tests
pytest tests/- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
python run.py- Connect GitHub repository to Render
- Set environment variables in Render dashboard
- Deploy with build command:
pip install -r requirements.txt - Start command:
python run.py
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "run.py"]/healthendpoint for service monitoring- Database activity logging
- Automatic server wake-up (Render compatibility)
- Error rate tracking
- Structured logging with timestamps
- Error tracking with stack traces
- Performance metrics collection
- Admin activity auditing
Bot not responding:
- Check BOT_TOKEN in .env file
- Verify internet connection
- Check logs for error messages
Location not accepted:
- Ensure GPS is enabled on device
- Check OFFICE_RADIUS setting
- Verify OFFICE_LATITUDE/LONGITUDE coordinates
Admin commands not working:
- Use
/add_admin <user_id>to grant privileges - Check user ID with
/myidcommand
For issues or questions:
- Check the logs:
tail -f attendance_bot.log - Review configuration in
.env - Verify dependencies:
pip list - Contact system administrator
This project is proprietary software developed for Mansoura CIH.
Developed for enhanced security and compliance in attendance tracking.
Version: 2.0.0
Last Updated: 2024
Office Location: 29R3+7Q El Mansoura 1
Security Level: High (Location-only enforcement)