✨ Simple. Fast. Digital. ✨
Mark your attendance in under 1 minute!
- What Is This?
- For Club Members (How to Use)
- Weekly Schedule
- For Developers (Complete Setup Guide)
- System Architecture
- Features
- FAQ
- Troubleshooting
- Support & Contact
This is the ICT Club's Digital Attendance System. Instead of signing paper sheets every session, you can now mark your attendance using your phone or computer in just a few taps!
No more:
- Waiting in line to sign paper sheets
- Lost or damaged attendance records
- Illegible handwriting
- Time wasted during sessions
Now you get:
- Mark attendance from anywhere (classroom, home, or on campus)
- Instant confirmation of your attendance
- Safe and secure digital records
- Quick and easy process (less than 1 minute!)
If you're new to the ICT Club:
- Open the system link (shared in WhatsApp group)
- Fill in your details:
- Registration Number (e.g.,
T/DEG/2024/123) - Full Name
- Email Address
- Phone Number
- Department(s) you're interested in
- Year of Study
- Gender
- Registration Number (e.g.,
- Click "Register"
- You're done!
Note: You only need to register ONCE. After that, just use your registration number to mark attendance.
Every Friday during club sessions (1:30 PM - 3:30 PM):
- Open the attendance system link
- Enter your Registration Number (e.g.,
T/DEG/2024/123) - Enter the Session Code (announced by department leaders)
- Click "Mark Attendance"
- You'll see a success message!
⏰ Attendance Window: You can mark attendance from Friday 1:00 PM until Saturday 12:00 AM (midnight). Don't miss it!
Every Friday, a different department presents. Here's the 6-week rotation:
| Week | Department | Session Code Format | Time |
|---|---|---|---|
| 1 | Networking | NETddMMM |
13:30-15:30 |
| 2 | Computer Maintenance | COMPddMMM |
13:30-15:30 |
| 3 | Graphic Design | GRAPHddMMM |
13:30-15:30 |
| 4 | AI & Machine Learning | AIddMMM |
13:30-15:30 |
| 5 | Cybersecurity | CYBERddMMM |
13:30-15:30 |
| 6 | Programming | PROGddMMM |
13:30-15:30 |
Example: NET30JAN for Networking on January 30th
💡 Pro Tip: The session code changes every week for security. Always wait for the official announcement during the session!
Before you begin, ensure you have:
- A computer (Windows, Mac, or Linux)
- Internet connection
- A Gmail account (for Google Cloud)
- Basic command line knowledge (optional but helpful)
-
Download Python:
- Visit: https://www.python.org/downloads/
- Click "Download Python 3.9+" (or latest version)
- Run the installer (
.exefile)
-
During Installation:
- CHECK: "Add Python to PATH" (IMPORTANT!)
- Click "Install Now"
- Wait for installation to complete
-
Verify Installation:
# Open Command Prompt (cmd) and type: python --version # Should show: Python 3.9.x or higher pip --version # Should show: pip 21.x.x or higher
-
Check if Python is installed:
python3 --version
-
If not installed, use Homebrew:
# Install Homebrew (if not installed) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Python brew install python@3.9
-
Verify Installation:
python3 --version pip3 --version
# Update package list
sudo apt update
# Install Python 3.9+
sudo apt install python3 python3-pip python3-venv
# Verify installation
python3 --version
pip3 --version# Clone the repository
git clone https://github.com/your-organization/ict-club-attendance-api.git
# Navigate to project directory
cd ict-club-attendance-api- Download the project ZIP from GitHub
- Extract to a folder (e.g.,
C:\Projects\ict-club-attendance-api) - Open terminal/command prompt in that folder
A virtual environment keeps your project dependencies isolated.
# Create virtual environment
python -m venv venv
# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Mac/Linux:
source venv/bin/activate
# You should see (venv) at the start of your command line# Make sure virtual environment is activated (you should see (venv))
# Install all required packages
pip install -r requirements.txt
# Wait for installation to complete (~2-5 minutes)Required Packages (automatically installed):
- Flask 3.0.0 - Web framework
- gspread 5.12.4 - Google Sheets integration
- oauth2client 4.1.3 - Google authentication
- python-dotenv 1.0.0 - Environment variables
- pytz 2023.3 - Timezone handling
- Flask-CORS 4.0.0 - Cross-origin requests
This is the most important part! Follow carefully.
-
Go to Google Cloud Console:
- Visit: https://console.cloud.google.com/
- Sign in with your Gmail account (preferably ICT Club email)
-
Accept Terms (first-time only):
- Read and check ☑ "I agree to the Terms of Service"
- Click "AGREE AND CONTINUE"
-
Create New Project:
- Click the project dropdown at the top (near "Google Cloud" logo)
- Click "NEW PROJECT"
- Fill in:
Project name: ICT-Club-Attendance Organization: No organization Location: No organization - Click "CREATE"
- Wait ~30 seconds
-
Verify Project is Selected:
- Look at top bar, should show: "ICT-Club-Attendance"
- If not, click dropdown and select your project
-
Navigate to APIs & Services:
- Click ☰ hamburger menu (top-left)
- Click "APIs & Services" → "Library"
-
Enable Google Sheets API:
- In search box, type:
Google Sheets API - Click on "Google Sheets API"
- Click "ENABLE" button
- Wait for confirmation
- In search box, type:
-
Enable Google Drive API (also required):
- Click "← APIs & Services" to go back
- Click "Library" again
- Search:
Google Drive API - Click on "Google Drive API"
- Click "ENABLE"
-
Go to Credentials:
- Click ☰ hamburger menu
- "APIs & Services" → "Credentials"
-
Create Service Account:
- Click "+ CREATE CREDENTIALS" (top)
- Select "Service Account"
-
Fill in Service Account Details:
Service account name: ict-club-attendance-sa Service account ID: (auto-generated, e.g., ict-club-attendance-sa@xxx.iam.gserviceaccount.com) Description: Service account for ICT Club attendance system- Click "CREATE AND CONTINUE"
-
Grant Permissions (SKIP THIS):
- Just click "CONTINUE" (no roles needed)
-
Grant Users Access (SKIP THIS):
- Click "DONE"
-
Find Your Service Account:
- On the "Credentials" page
- Scroll down to "Service Accounts" section
- You'll see your service account email (e.g.,
ict-club-attendance-sa@xxx.iam.gserviceaccount.com) - Click on the email
-
Create Key:
- Click the "KEYS" tab (top menu)
- Click "ADD KEY" button
- Select "Create new key"
-
Download JSON Key:
- Select "JSON" format
- Click "CREATE"
- A JSON file will download automatically (e.g.,
ict-club-attendance-xxxxxx.json)
-
Save the File:
- Rename it to:
credentials.json - Move it to your project folder:
ict-club-attendance-api/credentials.json ⚠️ IMPORTANT: Keep this file SECRET! Never share it or upload to GitHub!
- Rename it to:
-
Copy Service Account Email:
- Copy the service account email (e.g.,
ict-club-attendance-sa@xxx.iam.gserviceaccount.com) - You'll need this in the next step!
- Copy the service account email (e.g.,
-
Open Google Sheets:
- Visit: https://sheets.google.com/
- Sign in with the same Gmail account used for Google Cloud
-
Create New Spreadsheet:
- Click "+ Blank" to create a new sheet
- Rename it: "ICT Club Attendance" (click top-left "Untitled spreadsheet")
-
Create "Members" Sheet:
- The first sheet is already created
- Rename it to:
Members(double-click "Sheet1" tab at bottom) - Add headers in Row 1:
A1: reg_number B1: name C1: email D1: phone E1: departments F1: year_of_study G1: gender H1: registration_date
-
Create "Attendance_2026" Sheet:
- Click "+" button at bottom-left (next to "Members" tab)
- Rename new sheet to:
Attendance_2026 - Add headers in Row 1:
A1: reg_number B1: name (Dates will be added automatically by the system, e.g., C1: 2026-01-30, D1: 2026-02-06, etc.)
This is CRITICAL! The system can't access the sheets without this.
-
Click "Share" button (top-right corner of Google Sheets)
-
Add Service Account:
- Paste your service account email (from Step 5.4.5)
- Example:
ict-club-attendance-sa@xxx.iam.gserviceaccount.com
-
Set Permission:
- Change permission to: "Editor"
- Uncheck "Notify people" (service accounts don't get emails)
-
Click "Share" or "Send"
-
Copy Spreadsheet ID:
- Look at the URL in your browser
- URL format:
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID_HERE/edit - Copy the SPREADSHEET_ID (long string between
/d/and/edit) - Example:
1AbC2dEfGhIjKlMnOpQrStUvWxYz123456789
-
Create
.envfile in project root:# In the ict-club-attendance-api folder, create a new file named .env # On Windows: type nul > .env # On Mac/Linux: touch .env
-
Open
.envfile in a text editor (Notepad, VS Code, etc.) -
Add configuration:
# Flask Configuration FLASK_APP=src/app.py FLASK_ENV=development SECRET_KEY=your-secret-key-change-this-in-production # Google Sheets Configuration SPREADSHEET_ID=YOUR_SPREADSHEET_ID_HERE CREDENTIALS_FILE=credentials.json # Timezone TIMEZONE=Africa/Dar_es_Salaam # Application Settings DEBUG=True PORT=5000
-
Replace
YOUR_SPREADSHEET_ID_HEREwith the ID you copied in Step 6.2.5 -
Save the file
Your project should look like this:
ict-club-attendance-api/
├── credentials.json # ← Google Cloud credentials (SECRET!)
├── .env # ← Environment variables (SECRET!)
├── .gitignore # ← Git ignore file
├── requirements.txt # ← Python dependencies
├── README.md # ← This file
├── venv/ # ← Virtual environment (don't touch)
│
├── src/ # ← Main application code
│ ├── app.py # ← Flask app entry point
│ ├── config/ # ← Configuration files
│ │ ├── __init__.py
│ │ ├── config.py # ← App configuration
│ │ └── sessions.py # ← Session codes (update weekly!)
│ │
│ ├── api/ # ← API routes
│ │ ├── __init__.py
│ │ └── routes.py # ← API endpoints
│ │
│ ├── services/ # ← Business logic
│ │ ├── __init__.py
│ │ ├── sheets_service.py # ← Google Sheets operations
│ │ ├── member_service.py # ← Member management
│ │ └── attendance_service.py # ← Attendance logic
│ │
│ ├── utils/ # ← Helper functions
│ │ ├── __init__.py
│ │ └── validators.py # ← Input validation
│ │
│ ├── templates/ # ← HTML templates
│ │ ├── index.html
│ │ ├── register.html
│ │ └── attendance.html
│ │
│ └── static/ # ← CSS, JS, images
│ ├── css/
│ ├── js/
│ └── images/
│
├── docs/ # ← Documentation
│ ├── API_DOCUMENTATION.md
│ ├── DEPLOYMENT_GUIDE.md
│ └── SYSTEM_ARCHITECTURE.md
│
└── scripts/ # ← Deployment scripts
├── deploy.sh
└── pythonanywhere_deploy.sh
Time to test if everything works!
# Make sure you're in the project directory
cd ict-club-attendance-api
# Make sure virtual environment is activated
# You should see (venv) at the start of your command line
# If not:
# Windows: venv\Scripts\activate
# Mac/Linux: source venv/bin/activate
# Navigate to src folder
cd src
# Run the application
python app.pyExpected Output:
* Serving Flask app 'app'
* Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment.
* Running on http://127.0.0.1:5000
Press CTRL+C to quit
Test the Application:
- Open your browser
- Go to:
http://localhost:5000 - You should see the attendance system homepage!
Test Registration:
- Go to:
http://localhost:5000/register - Fill in a test member
- Submit
- Check your Google Sheet - new member should appear!
Now let's deploy to the internet so everyone can access it!
- Visit: https://www.pythonanywhere.com/
- Click "Start running Python online" or "Pricing & signup"
- Choose "Beginner" plan (FREE)
- Create account with email/password
- Verify your email
Option A: Using Git (Recommended)
-
Open Bash Console:
- In PythonAnywhere dashboard, click "Consoles" tab
- Click "Bash" to open a new console
-
Clone Repository:
git clone https://github.com/your-organization/ict-club-attendance-api.git cd ict-club-attendance-api
Option B: Upload Files Manually
- In PythonAnywhere, click "Files" tab
- Navigate to
/home/YOUR_USERNAME/ - Click "Upload a file"
- Upload your project files (or use "Upload Directory")
IMPORTANT: Don't upload credentials.json to GitHub!
- In PythonAnywhere Files tab:
- Navigate to
/home/YOUR_USERNAME/ict-club-attendance-api/ - Click "Upload a file"
- Upload your
credentials.jsonfile
- Navigate to
-
Open Bash Console (if not already open)
-
Navigate to project:
cd ~/ict-club-attendance-api
-
Create virtual environment:
mkvirtualenv --python=/usr/bin/python3.9 attendenv
-
Install dependencies:
pip install -r requirements.txt
- Go to "Web" tab in PythonAnywhere dashboard
- Click "Add a new web app"
- Click "Next" (accept free subdomain)
- Select "Manual configuration"
- Choose "Python 3.9"
- Click "Next"
- On Web tab, scroll to "Code" section
- Click on "WSGI configuration file" link
- Delete all content and replace with:
import sys
import os
# Add your project directory to the sys.path
project_home = '/home/YOUR_USERNAME/ict-club-attendance-api'
if project_home not in sys.path:
sys.path.insert(0, project_home)
# Set environment variables
os.environ['SPREADSHEET_ID'] = 'YOUR_SPREADSHEET_ID_HERE'
os.environ['CREDENTIALS_FILE'] = '/home/YOUR_USERNAME/ict-club-attendance-api/credentials.json'
os.environ['TIMEZONE'] = 'Africa/Dar_es_Salaam'
# Import Flask app
from src.app import app as application-
Replace:
YOUR_USERNAMEwith your PythonAnywhere usernameYOUR_SPREADSHEET_ID_HEREwith your Google Sheets ID
-
Save the file
- On Web tab, scroll to "Virtualenv" section
- Enter path:
/home/YOUR_USERNAME/.virtualenvs/attendenv - Click checkmark to save
- On Web tab, scroll to "Static files" section
- Click "Enter path"
- Add:
URL: /static Directory: /home/YOUR_USERNAME/ict-club-attendance-api/src/static
- Click green "Reload" button at top of Web tab
- Wait ~10 seconds
- Click on your website link (e.g.,
YOUR_USERNAME.pythonanywhere.com) - Test the system!
Troubleshooting:
- If you see errors, click "Log files" section on Web tab
- Check "Error log" for details
- Common issues:
- Wrong file paths in WSGI
- Missing credentials.json
- Wrong spreadsheet ID
┌─────────────────────────────────────────────────┐
│ USER (Phone/Computer Browser) │
│ Opens: your-app.com │
└────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ FLASK WEB APPLICATION │
│ ┌──────────────┐ ┌───────────────────────┐ │
│ │ Routes │──│ Business Logic │ │
│ │ (API URLs) │ │ (Validators) │ │
│ └──────────────┘ └───────────────────────┘ │
└────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ GOOGLE SHEETS API │
│ ┌──────────────────┐ ┌──────────────────────┐│
│ │ Members Sheet │ │ Attendance_2026 ││
│ │ (Member Data) │ │ (Attendance Data) ││
│ └──────────────────┘ └──────────────────────┘│
└─────────────────────────────────────────────────┘
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Homepage |
/register |
GET | Registration form |
/api/register |
POST | Register new member |
/api/check-member |
POST | Verify member exists |
/api/mark-attendance |
POST | Mark attendance |
/api/session-info |
GET | Get current session info |
-
Member Registration
- Self-registration for new members
- Registration number validation (
T/DEG/YYYY/XXXorT/DIP/YYYY/XXX) - Multi-department membership support
- Stores: name, email, phone, gender, year of study
-
Attendance Marking
- Session code validation (changes weekly)
- Time-window enforcement (Friday 13:00 → Saturday 00:00)
- Duplicate attendance prevention
- Instant confirmation messages
-
Session Management
- 6 rotating departments (weekly schedule)
- Hardcoded session codes for security
- Automatic session detection based on date
-
Data Storage
- Real-time Google Sheets integration
- Members sheet with all registered members
- Attendance sheet with date-based columns
- Automatic data backup
-
User Interface
- Simple and clean design
- Mobile-responsive (works on all devices)
- Two-step process: Reg Number → Session Code
- Clear error messages
- Registration number format validation
- Session code validation (weekly changes)
- Time-window enforcement
- Duplicate attendance prevention
- Service account authentication (Google Sheets)
- Environment variables for sensitive data
Q: What if I forget my registration number?
A: Check your student ID card. Your registration number is your university registration number (e.g., T/DEG/2024/123).
Q: Can I mark attendance after the session ends?
A: Yes! You have until Saturday midnight (11 hours after the session) to mark attendance.
Q: What if I enter the wrong session code?
A: The system will reject it and show an error. Make sure you get the correct code from the department leader during the session.
Q: Can I belong to multiple departments?
A: Absolutely! During registration, you can select multiple departments.
Q: Do I need internet to use this?
A: Yes, you need internet connection (campus WiFi or mobile data).
Q: Can I use Python 3.8 or older?
A: No, Python 3.9+ is required for compatibility with Flask 3.0.
Q: Why use Google Sheets instead of a database?
A: Google Sheets is free, easy to setup, accessible to non-technical club leaders, and sufficient for our needs (~60 members).
Q: Can I deploy to Heroku instead of PythonAnywhere?
A: Yes, but you'll need to adjust the deployment scripts. PythonAnywhere is recommended for beginners.
Q: How do I update session codes weekly?
A: Edit src/config/sessions.py file and add new session codes following the existing format.
Q: Is this system scalable?
A: For 100-200 members, yes. Beyond that, consider migrating to PostgreSQL or MongoDB.
Problem: "Module not found" error
Solution: Make sure virtual environment is activated and all dependencies are installed (pip install -r requirements.txt)
Problem: "Invalid credentials" error
Solution: Check that credentials.json exists and SPREADSHEET_ID is correct in .env file
Problem: "Permission denied" when accessing sheets
Solution: Make sure you shared the Google Sheet with your service account email (Editor permission)
Problem: "Invalid registration number" error
Solution: Registration number must follow format: T/DEG/YYYY/XXX or T/DIP/YYYY/XXX
Problem: "Session not open" error
Solution: Attendance can only be marked between Friday 1:00 PM and Saturday 12:00 AM
Problem: Application not loading on PythonAnywhere
Solution: Check error logs on Web tab, verify WSGI configuration, and ensure virtual environment is set correctly
Planned features for upcoming versions:
- Admin Dashboard - View reports and statistics
- Email Reminders - Automatic session reminders
- QR Code Check-in - Faster attendance marking
- Analytics - Attendance trends and insights
- Offline Mode - Mark attendance without internet
- Certificates - Auto-generate based on attendance
- Push Notifications - Mobile alerts for sessions
- Mobile App - Native iOS/Android apps
- During Sessions: Ask session presenters or club leaders
- Technical Issues: Contact ICT Club technical team
- General Questions: Message the club WhatsApp group
- Email: ictclub@example.com
- Location: Your Institution
- Meeting Time: Check with your club schedule
Special thanks to:
- ICT Club Leaders - For guidance and support
- Club Members - For embracing digital transformation
- Faculty Advisor - For approving this initiative
- Department Heads - For coordinating sessions
- Open Source Community - For Flask, Python, and amazing tools
This project is developed for ICT Club. See LICENSE file for details.
🎓 ICT CLUB
Empowering students through technology
Built with ❤️ by ICT Club Development Team
Version 1.0