📖 Hafez Streamlit

A web application for managing and tracking Quran memorization built with Streamlit. Specifically designed for Islamic schools and teachers to easily monitor students' progress in memorization and review.

✨ Key Features

📊 Report Management

• 📅 Automatic Arabic reports with date stamps
• 📋 Copy reports to clipboard and WhatsApp sharing
• 📤 Export data as CSV files
• 🔍 Search and filter students by name and performance level
• 🗂️ Filter by performance levels (Excellent, Very Good, Good, Weak)
• 📚 Track memorized and reviewed Surahs with verse counts

👥 Student Management

• 📥 Import student lists from CSV files
• ✏️ Edit individual student data
• 🗑️ Delete individual or bulk students
• 🔍 Quick search through student lists
• 📋 Ready-to-download CSV template

🎯 Additional Features

• 📱 Responsive design for mobile and tablet devices
• 🍪 Data persistence in browser session
• 🌐 Complete Arabic interface
• ⚡ Fast performance and user-friendly experience

🚀 Installation and Setup

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Quick Installation

1. Download the Project

git clone https://github.com/ztsmhmd/hafez-streamlit.git
cd hafez-streamlit

2. Run the Application (Quick Method)

chmod +x run.sh
./run.sh

The run.sh script will:

• Create virtual environment automatically
• Install all required packages
• Launch the application

3. Manual Installation (Optional)

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Linux/Mac:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install packages
pip install -r requirements.txt

# Run the application
streamlit run app.py

🌐 Access the Application

After running, open your browser and go to:

http://localhost:8501

📱 How to Use

Reports Page

1. Add New Student:

   • Enter student name
   • Select memorization level (Excellent, Very Good, Good, Weak)
   • Choose memorized Surah (optional)
   • Select review level
   • Choose review Surah (optional)

2. Generate Report:

   • Use filter options to search for specific students
   • View formatted Arabic report
   • Copy report to clipboard or export as CSV

Student Management Page

1. Import Students:

   • Download CSV template from the app
   • Fill in the data in the file
   • Upload the file to the application

2. Edit Students:

   • Search for the desired student
   • Edit their data from the popup window
   • Save changes or delete the student

📋 CSV File Format

The CSV file must contain the following columns:

Column	Description	Example
name	Student name	Ahmed Mohamed
memorization_level	Memorization level	Excellent
memorized_surah	Memorized Surah	Al-Baqarah
review_level	Review level	Good
reviewed_surah	Review Surah	Al-Fatihah

CSV File Example:

name,memorization_level,memorized_surah,review_level,reviewed_surah
Ahmed Mohamed,Excellent,Al-Baqarah,Good,Al-Fatihah
Fatima Ali,Very Good,Aal-E-Imran,Excellent,Al-Baqarah
Mohamed Ahmed,Good,An-Nisa,Very Good,Aal-E-Imran

🛠️ Technologies Used

• Streamlit - Web application framework
• Pandas - Data processing and CSV handling
• Pyperclip - Clipboard text copying
• Python 3.8+ - Core programming language

📁 Project Structure

hafez-streamlit/
├── app.py              # Main application file
├── quran.json          # Quran Surahs data
├── requirements.txt    # Required packages list
├── run.sh             # Quick launch script
├── README.md          # Project documentation
├── LICENSE            # Project license
└── .gitignore         # Git ignored files

🤝 Contributing

We welcome your contributions to improve the project:

1. Fork the project
2. Create a new 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

📄 License

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

📞 Support and Contact

• 🐛 Report Issues: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Direct Contact: [email protected]

🙏 Acknowledgments

• Special thanks to all teachers who contribute to Quran memorization
• Thanks to the Streamlit community for the amazing tools
• Thanks to everyone who contributed to developing this project

---

May Allah make this work in the balance of our good deeds 🤲