🎯 Smart Attendance System Complete

Enterprise-Grade, Multi-Modal AI Attendance & Biometric Management System

---

Key Features • Tech Stack • Getting Started • Architecture • API Reference • Biometric Bridge

---

🌟 Overview

Smart Attendance System Complete is a state-of-the-art, multi-tenant Attendance & Biometric Management platform built with Flask, OpenCV, and SQLAlchemy. Designed for educational institutions, corporate offices, and organizations, it delivers multi-modal attendance verification through AI Face Recognition, QR / Barcode Scanning, and Hardware Fingerprint Sensors.

---

✨ Key Features

🤖 1. AI Face Recognition Attendance

• Real-time face detection & encoding using OpenCV and MediaPipe / Face-Recognition.
• Instant identity matching with low-latency camera stream processing.
• Single-click face profile enrollment.

📱 2. QR Code & Barcode Scanning

• Rapid attendance marking via USB scanner or webcam stream using PyZbar.
• Automated digital ID barcode generation for members and employees.

☝️ 3. Hardware Fingerprint Sensor Bridge

• Dedicated serial communication bridge (bridge/fingerprint_bridge.py) supporting optical & capacitive fingerprint hardware over PySerial.
• Real-time template registration and fingerprint matching.

🏢 4. Multi-Tenant Organization & RBAC

• Dynamic Organization hierarchy: Groups, Departments, Offices, and Classes.
• Role-Based Access Control (Super Admin, Org Admin, Manager, Member).
• Secure authentication powered by Flask-JWT-Extended with HTTP-only cookies and bcrypt hashing.

📊 5. Analytics & Exportable Reports

• Visual dashboard showcasing today's attendance rate, absent counts, and active sessions.
• Automated report generation in PDF (via WeasyPrint) and CSV formats.
• Historical session tracking and manual override controls for administrators.

🔌 6. Enterprise RESTful API v1

• Full JSON REST API endpoints (/api/v1/...) enabling integration with mobile apps, desktop clients, and IoT edge devices.

---

🛠️ Tech Stack

Component	Technologies Used
Backend Framework	Flask 3.1 • Flask-SQLAlchemy • Flask-Migrate
Security & Auth	Flask-JWT-Extended • Bcrypt • Python-Dotenv
Computer Vision	OpenCV (opencv-python) • PyZbar • NumPy
Hardware Bridge	PySerial (RS232/UART/USB Serial)
Database	PostgreSQL / MySQL / SQLite
Frontend UI	HTML5 • CSS3 • JavaScript (ES6+) • Jinja2 Templates
Report Engine	WeasyPrint (PDF Generation)

---

🏗️ Project Architecture

Smart Attendance System Complete/
├── app/                        # Main Application Package
│   ├── api/v1/                 # RESTful API Endpoints (Auth, Attendance, Members)
│   ├── blueprints/             # Web Route Controllers
│   │   ├── attendance/         # Attendance sessions & marking
│   │   ├── auth/               # User authentication & registration
│   │   ├── biometric/          # Face, QR & Fingerprint routes
│   │   ├── dashboard/          # Analytics dashboard
│   │   ├── groups/             # Group & Department management
│   │   ├── members/            # Member CRUD operations
│   │   ├── reports/            # PDF/CSV Export reports
│   │   └── settings/           # Organization settings
│   ├── models/                 # SQLAlchemy Database Models
│   ├── config.py               # Flask Configuration Loader
│   └── extensions.py           # Flask Extensions (DB, JWT, Migrate, CORS)
├── bridge/                     # Hardware Hardware Bridges
│   └── fingerprint_bridge.py   # Serial communication bridge for sensors
├── Templates/                  # Jinja2 HTML View Templates
├── migrations/                 # Alembic Database Migrations
├── requirements.txt            # Python Dependencies
├── run.py                      # Application Entry Point
└── setup_db.py                 # Database Initialization Script

---

🚀 Getting Started

📋 Prerequisites

• Python 3.10+ installed on your system.
• MySQL (Community / XAMPP / Docker) or PostgreSQL database server.
• Webcam (for Face & QR recognition).
• USB Fingerprint Scanner (optional for fingerprint verification).

---

📥 1. Installation

Clone the repository and enter the directory:

git clone https://github.com/Omnagar/Smart-Attendance-System-Complete.git
cd "Smart Attendance System Complete"

Create and activate a virtual environment:

# Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

Install the dependencies:

pip install -r requirements.txt

---

⚙️ 2. Environment Configuration

Copy .env.example to .env and configure your credentials:

cp .env.example .env

Edit .env:

FLASK_ENV=development
SECRET_KEY=your_super_secret_app_key
JWT_SECRET_KEY=your_super_secret_jwt_key
DATABASE_URL=postgresql://postgres:password@localhost:5432/attendance_db
# Or for MySQL:
# DATABASE_URL=mysql+psycopg2://root:password@localhost:3306/attendance_db

---

🗄️ 3. Initialize Database

Run the database setup script to create tables and seed default administrator credentials:

python setup_db.py

Or use Flask-Migrate:

flask db upgrade

---

▶️ 4. Run the Application

Start the Flask development server:

python run.py

Open your browser and navigate to: 👉 http://127.0.0.1:5000

Default Admin Login:

• Email: admin@organization.com (or set up during first launch)
• Password: admin123

---

🔌 API Reference

The application provides a structured REST API under /api/v1/:

Method	Endpoint	Description	Auth Required
POST	/api/v1/auth/login	Authenticate & get JWT token	❌
POST	/api/v1/auth/register	Register new organization / user	❌
GET	/api/v1/members/	Get list of organization members	✅
POST	/api/v1/members/	Create a new member	✅
GET	/api/v1/attendance/sessions	List active & past attendance sessions	✅
POST	/api/v1/attendance/mark	Mark attendance record (Face/QR/Fingerprint)	✅

---

☝️ Biometric & Hardware Bridge

To connect a physical hardware fingerprint scanner (e.g. Optical UART Sensor connected via USB-to-Serial converter):

1. Connect your sensor to your machine's COM port (e.g. COM3 on Windows or /dev/ttyUSB0 on Linux).
2. Launch the hardware bridge daemon:

   python bridge/fingerprint_bridge.py --port COM3 --baud 57600

3. The bridge communicates live with the Web App to process biometric enrollment and match scans in real time.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check out the issues page.

1. Fork the Project (git checkout -b feature/AmazingFeature)
2. Commit your Changes (git commit -m 'Add some AmazingFeature')
3. Push to the Branch (git push origin feature/AmazingFeature)
4. Open a Pull Request

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

_{Built with ❤️ by Omnagar}