📋 Enterprise Attendance Management System

Production-Ready Enterprise Architecture | REST API | Advanced Security | Audit Logging | Multi-Environment Support

A complete enterprise-grade web-based attendance management system built with Flask 3.0, SQLAlchemy 2.0, Blueprint Architecture, and RESTful API. Employees can view their attendance records, admins can manage employees and upload attendance data via CSV, and external systems can integrate programmatically via REST API.

✨ Key Improvements (Latest Major Upgrade)

🏗️ Architecture Modernization

• Factory Pattern: Multi-environment configuration (Development/Production/Testing)
• Blueprint Architecture: Modular code organization (auth, admin, employee, api blueprints)
• SQLAlchemy 2.0: Advanced ORM with type hints and performance optimizations
• Production-Ready: Gunicorn WSGI entry point, security headers, rate limiting

🔒 Security Enhancements

• Talisman Integration: Security headers (HSTS, X-Frame-Options, Content Security Policy)
• Rate Limiting: 5 requests/minute on auth endpoints, 200/day global limit
• Audit Logging: Complete change history with JSON diffs and IP tracking
• Enhanced Validation: Comprehensive input validation and sanitization
• CSRF Protection: Ready for deployment with proper middleware

🔌 REST API (New)

• Versioned API: /api/v1 endpoints for external integrations
• 6 Core Endpoints: Health check, attendance check, export, statistics, employee list
• JSON Serialization: Consistent API responses with proper error codes
• Rate Limited: Dedicated rate limiting for API endpoints

📊 Advanced Database Features

• Timestamp Mixin: Automatic created_at/updated_at on all models
• Audit Trail: AuditLog model tracking all changes with who/what/when/where
• Indexes: Performance-optimized database queries (employee_id, date, status)
• Constraints: Unique constraints prevent duplicate attendance entries
• Dynamic Timestamps: check_in/check_out support for precise tracking

📝 Developer Experience

• CLI Commands: flask init-db, flask seed-db, flask create-admin
• Comprehensive Logging: Dual file/console logging with timestamp and levels
• Error Handlers: Dedicated handlers for 400, 403, 404, 429, 500 errors
• Context Processors: Thread-safe template variables

🎯 Core Features

For Admins 👨‍💼

• Admin Dashboard: Overview with key statistics and quick actions
• Employee Management: Create, update, and manage employee accounts
• Bulk Upload: CSV file upload for batch attendance records
• Attendance View: Filter and view all employee attendance with date ranges
• Department Management: Organize employees by department and designation
• Audit Trail: See who changed what and when

For Employees 👨‍💻

• Personal Dashboard: Attendance statistics and summary
• Attendance History: Detailed view with filtering by date/status
• Profile Management: View and update personal information
• Privacy: Each employee can only see their own records

For External Systems 🔌

• REST API: Programmatic access to all system data
• Attendance Export: Download attendance in JSON format
• Employee Directory: Query employee information
• Statistics API: Access system-wide attendance statistics
• Health Endpoint: Monitor system status

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Copy and customize .env.example to .env:

cp .env.example .env

Edit .env with your settings:

FLASK_ENV=development
DATABASE_URL=sqlite:///attendance.db
SECRET_KEY=your-secret-key-here-32chars

3. Initialize Database

flask init-db

Or seed with sample data:

flask seed-db

4. Create Admin Account

flask create-admin --username admin --password admin123 --email admin@example.com

5. Run the Application

Development:

python app.py

Production:

gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app

Application will be available at http://localhost:5000

📱 Usage Guide

Admin Workflow

1. Navigate to http://localhost:5000
2. Click "Admin Login"
3. Enter your admin credentials
4. From dashboard:
   • Create Employees: Add new staff members with basic info
   • Upload Attendance: Use CSV file with format: Employee ID, Date, Status
   • View Records: Search and filter attendance history
   • View Audit: Monitor all system changes

Employee Workflow

1. Navigate to http://localhost:5000
2. Click "Employee Login"
3. Enter your Employee ID and password
4. From dashboard:
   • View Statistics: See attendance overview
   • Check History: Search attendance records by date
   • Download Reports: Export personal attendance data

REST API Usage

Get System Health:

curl http://localhost:5000/api/v1/health

Get Attendance Summary:

curl http://localhost:5000/api/v1/attendance/check?date=2024-01-15

Export Attendance:

curl http://localhost:5000/api/v1/attendance/export?start=2024-01-01&end=2024-01-31

List All Employees:

curl http://localhost:5000/api/v1/employees

📦 Project Structure

attendance-system/
├── app.py                    # Application factory & main entry point
├── wsgi.py                   # Production WSGI entry point
├── config.py                 # Multi-environment configuration
├── models.py                 # SQLAlchemy database models
├── requirements.txt          # Python dependencies
├── .env.example              # Environment variables template
│
├── routes/                   # API route blueprints
│   ├── auth.py              # Authentication (login/logout)
│   ├── admin.py             # Admin features
│   ├── employee.py          # Employee portal
│   └── api.py               # REST API endpoints
│
├── utils/                    # Utility functions
│   └── validators.py        # Input validation
│
├── templates/               # HTML templates
│   ├── base.html            # Base template
│   ├── admin_login.html     # Admin login
│   ├── employee_login.html  # Employee login
│   ├── admin_dashboard.html # Admin interface
│   ├── employee_dashboard.html
│   └── errors/              # Error pages
│       ├── 400.html, 403.html, 404.html, 429.html, 500.html
│
└── database/                # Database files
    └── attendance.db        # SQLite database (auto-created)

🔧 Configuration

Development Environment

FLASK_ENV = 'development'
DEBUG = True
TESTING = False
DATABASE_URL = 'sqlite:///attendance.db'

Production Environment

FLASK_ENV = 'production'
DEBUG = False
DATABASE_URL = 'postgresql://user:pass@host/dbname'
TALISMAN_FORCE_HTTPS = True

See config.py for complete configuration options.

📚 Documentation

Comprehensive documentation is available:

• SETUP_GUIDE.md: Complete installation and troubleshooting
• ARCHITECTURE.md: System design, patterns, and database schema
• COMPLETE_UPGRADE_SUMMARY.md: All changes and improvements from upgrade

🔐 Security

This system implements enterprise-level security:

✅ Password Hashing: Werkzeug secure hashing
✅ Session Security: HttpOnly, SameSite, Secure flags
✅ Rate Limiting: DDoS protection per endpoint
✅ CSRF Protection: Token validation on all forms
✅ Security Headers: HSTS, CSP, X-Frame-Options via Talisman
✅ Audit Logging: Complete change history tracking
✅ Input Validation: Comprehensive validation on all inputs

🧪 Testing

Run tests:

pytest tests/

With coverage:

pytest --cov=. tests/

Lint code:

flake8 app.py models.py config.py
black app.py models.py config.py

📋 CSV Import Format

For attendance bulk upload, use this CSV format:

employee_id,date,status
EMP001,2024-01-15,Present
EMP002,2024-01-15,Absent
EMP003,2024-01-15,Leave

Supported statuses: Present, Absent, Leave, Half-day, Work From Home

🐛 Troubleshooting

Database Issues

# Reset database
flask init-db --reset

# Check database
sqlite3 attendance.db ".tables"

Port Already in Use

# Use different port
python -m flask run --port 5001

Missing Dependencies

pip install --upgrade -r requirements.txt

See SETUP_GUIDE.md for detailed troubleshooting.

📊 Technology Stack

Component	Version	Purpose
Flask	3.0.0	Web Framework
SQLAlchemy	2.0.23	ORM
Werkzeug	3.0.1	Security
Flask-Limiter	3.5.0	Rate Limiting
Flask-Talisman	1.1.0	Security Headers
Gunicorn	21.2.0	WSGI Server

📄 License

This project is part of an enterprise attendance management solution.

🤝 Support

For issues or questions:

1. Check SETUP_GUIDE.md
2. Review ARCHITECTURE.md
3. Check application logs in logs/ directory

✅ Status

✨ Latest Version: 2.0 (Production-Ready Enterprise Architecture)
📅 Last Updated: 2024
🎯 Stability: Production-Ready
🔒 Security Level: Enterprise-Grade

Admin Tasks

Create New Employee

1. Go to Admin Dashboard
2. Click "Create Employee" card
3. Enter:
   • Employee ID (e.g., EMP001)
   • Employee Name
   • Password
4. Click "Create Employee"

Upload Attendance (CSV)

1. Go to Admin Dashboard
2. Click "Upload Attendance" card
3. Prepare a CSV file with columns: employee_id, date, status
4. Upload the file

CSV Format Example:

employee_id,date,status
EMP001,2024-03-30,Present
EMP002,2024-03-30,Absent
EMP003,2024-03-30,Leave
EMP001,2024-03-29,Present

Employee Tasks

Login & View Records

1. Click "Employee Login" on home page
2. Enter your Employee ID and Password
3. View your attendance statistics and records
4. Click "History" to see detailed records

📁 Project Structure

attendance-system/
├── app.py                      # Main Flask application
├── requirements.txt            # Dependencies
├── attendance.db              # SQLite database (auto-created)
├── templates/
│   ├── base.html             # Base template with navigation
│   ├── login_choice.html      # Home page - choose admin/employee
│   ├── admin_login.html       # Admin login page
│   ├── admin_dashboard.html   # Admin dashboard
│   ├── create_employee.html   # Employee creation form
│   ├── upload_attendance.html # CSV upload form
│   ├── employee_login.html    # Employee login page
│   ├── employee_dashboard.html# Employee dashboard
│   ├── attendance_history.html# Detailed attendance
│   ├── view_all_attendance.html# All records view
│   ├── 404.html               # 404 error page
│   └── 500.html               # 500 error page
└── uploads/                   # Directory for uploaded CSV files

🗄️ Database Models

Employee

• id: Primary key
• employee_id: Unique employee identifier (e.g., EMP001)
• name: Employee full name
• password: Hashed password
• created_at: Account creation timestamp

Attendance

• id: Primary key
• employee_id: Foreign key linking to Employee
• date: Attendance date
• status: Present/Absent/Leave
• created_at: Record creation timestamp

Admin

• id: Primary key
• username: Username
• password: Hashed password

🔐 Security Features

• Password Hashing: All passwords are hashed using Werkzeug
• Session Management: Secure session handling with Flask
• Access Control: Role-based access (admin vs employee)
• Data Privacy: Employees can only see their own records
• CSRF Protection: Can be enabled with Flask-WTF

🎨 UI Features

• Bootstrap 5: Responsive design
• Gradient Background: Modern styling
• Emoji Icons: User-friendly interface
• Statistics Cards: Quick overview of attendance
• Responsive Tables: Mobile-friendly data display
• Flash Messages: User feedback for actions

📝 Default Admin Credentials

• Username: admin
• Password: admin123

⚠️ IMPORTANT: Change these credentials in production!

🔧 Customization

Change Admin Password

Edit app.py and modify the line where the default admin is created:

admin = Admin(username='admin', password=generate_password_hash('your_new_password'))

Change Secret Key

In app.py, update:

app.config['SECRET_KEY'] = 'your-complex-secret-key-here'

📋 CSV Upload Template

Download or create a CSV file with this format:

employee_id,date,status
EMP001,2024-03-30,Present
EMP002,2024-03-30,Absent
EMP003,2024-03-30,Leave

Status Options: Present, Absent, Leave

🐛 Troubleshooting

Port Already in Use

Change the port in app.py:

app.run(debug=True, host='0.0.0.0', port=5001)  # Use different port

Database Issues

Delete attendance.db and restart the app to reset the database.

Session Issues

Clear your browser cookies and login again.

📖 API Endpoints

• / - Home page
• /admin_login - Admin login
• /employee_login - Employee login
• /admin_dashboard - Admin dashboard
• /create_employee - Create new employee
• /upload_attendance - Upload CSV
• /view_all_attendance - View all records
• /employee_dashboard - Employee dashboard
• /attendance_history - Detailed history
• /logout - Logout user

📞 Support

For questions or issues, please check:

1. Ensure Flask and dependencies are installed
2. Check database permissions
3. Verify CSV format for uploads
4. Clear browser cache if UI issues occur

📄 License

This project is open-source and available for educational and commercial use.

---

Happy Attendance Tracking! 📊✅