{"id":42035872,"url":"https://github.com/nem-web/smart-attendance","last_synced_at":"2026-01-26T05:06:22.846Z","repository":{"id":327175947,"uuid":"1107671729","full_name":"nem-web/smart-attendance","owner":"nem-web","description":"A modern, dual-portal web application that automates classroom attendance using real-time face recognition and provides detailed analytics for teachers and students.","archived":false,"fork":false,"pushed_at":"2026-01-19T03:32:12.000Z","size":4970,"stargazers_count":2,"open_issues_count":2,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-19T12:47:44.107Z","etag":null,"topics":["computer-vision","nodejs","python","reactjs","tailwindcss"],"latest_commit_sha":null,"homepage":"https://sa-gl.vercel.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nem-web.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-01T13:08:12.000Z","updated_at":"2026-01-19T03:24:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nem-web/smart-attendance","commit_stats":null,"previous_names":["nem-web/smart-attendance"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nem-web/smart-attendance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nem-web%2Fsmart-attendance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nem-web%2Fsmart-attendance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nem-web%2Fsmart-attendance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nem-web%2Fsmart-attendance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nem-web","download_url":"https://codeload.github.com/nem-web/smart-attendance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nem-web%2Fsmart-attendance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28767025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T03:54:34.369Z","status":"ssl_error","status_checked_at":"2026-01-26T03:54:33.031Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","nodejs","python","reactjs","tailwindcss"],"created_at":"2026-01-26T05:06:22.035Z","updated_at":"2026-01-26T05:06:22.837Z","avatar_url":"https://github.com/nem-web.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎓 Smart Attendance System\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub stars](https://img.shields.io/github/stars/nem-web/smart-attendance?style=social)](https://github.com/nem-web/smart-attendance/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/nem-web/smart-attendance?style=social)](https://github.com/nem-web/smart-attendance/network/members)\n[![GitHub issues](https://img.shields.io/github/issues/nem-web/smart-attendance)](https://github.com/nem-web/smart-attendance/issues)\n[![GitHub pull requests](https://img.shields.io/github/issues-pr/nem-web/smart-attendance)](https://github.com/nem-web/smart-attendance/pulls)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**An intelligent, AI-powered attendance management system built with facial recognition technology**\n\n[Features](#-features) • [Installation](#-installation) • [Documentation](#-api-documentation) • [Contributing](#-contributing) • [Demo](#-live-demo)\n\n\u003c/div\u003e\n\n---\n\n## 📖 About The Project\n\nSmart Attendance is a modern, intelligent attendance management system designed for educational institutions. It leverages cutting-edge facial recognition technology to automate attendance tracking, making it faster, more accurate, and significantly easier to manage. The system provides real-time analytics, comprehensive dashboards, and intelligent reporting features for both teachers and students.\n\n### Why Smart Attendance?\n\n- ⏱️ **Save Time**: Automated attendance marking reduces manual work\n- 🎯 **Improve Accuracy**: AI-powered facial recognition eliminates errors\n- 📊 **Gain Insights**: Real-time analytics and predictive forecasting\n- 🔐 **Stay Secure**: OAuth 2.0 authentication with Google Sign-In\n- 📱 **Access Anywhere**: Responsive design works on all devices\n\n---\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Tech Stack](#-tech-stack)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n  - [Backend Setup](#backend-setup)\n  - [Frontend Setup](#frontend-setup)\n  - [Environment Variables](#environment-variables)\n- [Usage](#-usage)\n  - [For Teachers](#for-teachers)\n  - [For Students](#for-students)\n- [Docker Deployment](#-docker-deployment)\n- [Project Structure](#-project-structure)\n- [API Documentation](#-api-documentation)\n- [Screenshots](#-screenshots)\n- [Contributing](#-contributing)\n- [Security](#-security)\n- [Roadmap](#-roadmap)\n- [License](#-license)\n- [Support](#-support)\n- [Authors](#-authors)\n- [Acknowledgments](#-acknowledgments)\n\n---\n\n## ✨ Features\n\n### 🎓 For Teachers\n\n- **📸 Facial Recognition Attendance**: Mark attendance using advanced facial recognition through webcam\n- **👨‍🏫 Comprehensive Dashboard**: View attendance statistics, trends, and analytics at a glance\n- **📊 Real-time Analytics**: Monitor total students, daily attendance, and average attendance rates\n- **📈 Subject Management**: Manage multiple subjects and classes efficiently\n- **👥 Student Management**: Add, view, and manage student records with attendance percentages\n- **⚠️ At-Risk Detection**: Automatically identify students with low attendance (\u003c75%)\n- **📧 Email Notifications**: Send automated alerts to students with poor attendance\n- **📅 Attendance Reports**: Generate and export detailed attendance reports\n- **⚙️ Teacher Settings**: Customize notification preferences and profile settings\n- **🔐 Google OAuth Login**: Secure authentication with Google Sign-In\n\n### 🎓 For Students\n\n- **📱 Student Dashboard**: Personal dashboard with attendance overview\n- **📚 Subject View**: Track attendance across all enrolled subjects\n- **📈 Attendance Forecast**: Predict future attendance and plan accordingly\n- **👤 Profile Management**: View and update personal information\n- **📊 Visual Analytics**: Charts and graphs showing attendance trends\n- **🔔 Low Attendance Alerts**: Get notified when attendance falls below threshold\n\n### 🎨 General Features\n\n- **🎨 Theme Support**: Multiple theme options (Light, Dark, Soft) for better user experience\n- **📱 Responsive Design**: Seamlessly works across desktop, tablet, and mobile devices\n- **🌐 OAuth 2.0 Authentication**: Secure login with Google integration\n- **💾 Cloud Storage**: Profile pictures stored securely on Cloudinary\n- **🗄️ MongoDB Database**: Scalable and flexible data storage\n- **🚀 High Performance**: Built with FastAPI for lightning-fast API responses\n\n---\n\n## 🛠️ Tech Stack\n\n### Frontend\n\n| Technology | Version | Purpose |\n|-----------|---------|---------|\n| **React** | 19.2.0 | Modern UI library for building interactive interfaces |\n| **React Router DOM** | 7.9.6 | Client-side routing and navigation |\n| **Vite** | 7.2.4 | Lightning-fast build tool and dev server |\n| **Tailwind CSS** | 4.1.17 | Utility-first CSS framework for styling |\n| **Material-UI** | 7.3.5 | React UI component library |\n| **Recharts** | 3.5.1 | Composable charting library for data visualization |\n| **React Webcam** | 7.2.0 | Webcam component for capturing images |\n| **Axios** | 1.13.2 | Promise-based HTTP client |\n| **TanStack Query** | 5.90.12 | Powerful data fetching and state management |\n| **Lucide React** | 0.555.0 | Beautiful \u0026 consistent icon toolkit |\n\n### Backend API\n\n| Technology | Version | Purpose |\n|-----------|---------|---------|\n| **FastAPI** | 0.115.5 | High-performance Python web framework |\n| **Uvicorn** | 0.32.1 | Lightning-fast ASGI server |\n| **MongoDB** | - | NoSQL database for flexible data storage |\n| **Motor** | - | Asynchronous MongoDB driver for Python |\n| **PyJWT** | - | JSON Web Token implementation |\n| **Cloudinary** | - | Cloud-based image storage and management |\n| **Passlib** | 1.7.4 | Password hashing library |\n| **Python Dotenv** | - | Environment variable management |\n| **Authlib** | - | OAuth and authentication library |\n\n### ML Service\n\n| Technology | Version | Purpose |\n|-----------|---------|---------|\n| **FastAPI** | 0.115.5 | High-performance Python web framework |\n| **Uvicorn** | 0.32.1 | Lightning-fast ASGI server |\n| **MediaPipe** | 0.10.9 | Face detection and mesh analysis |\n| **OpenCV** | - | Computer vision and image processing |\n| **NumPy** | 1.26.4 | Numerical computing library |\n| **Pillow** | 11.0.0 | Python Imaging Library |\n| **Scikit-learn** | - | Machine learning utilities |\n\n---\n\n## 📦 Prerequisites\n\nBefore you begin, ensure you have the following installed on your system:\n\n- **Node.js** (v18.0 or higher) - [Download](https://nodejs.org/)\n- **npm** (v8.0 or higher) - Comes with Node.js\n- **Python** (v3.10 or higher) - [Download](https://www.python.org/)\n- **pip** (Latest version) - Comes with Python\n- **MongoDB** (v5.0 or higher) - [Download](https://www.mongodb.com/try/download/community)\n- **Git** - [Download](https://git-scm.com/)\n- **Modern web browser** with webcam support (Chrome, Firefox, Edge, Safari)\n\n### Optional but Recommended\n\n- **Docker** and **Docker Compose** - For containerized deployment\n- **Virtual Environment** - For Python dependency isolation\n\n---\n\n## 🚀 Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/nem-web/smart-attendance.git\ncd smart-attendance\n```\n\n### 2. Backend API Setup\n\n#### Step 1: Navigate to Backend API Directory\n\n```bash\ncd server/backend-api\n```\n\n#### Step 2: Create and Activate Virtual Environment\n\n**On Windows:**\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\n```\n\n**On macOS/Linux:**\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n#### Step 3: Install Dependencies\n\n```bash\npip install --upgrade pip\npip install -r requirements.txt\n```\n\n#### Step 4: Setup Environment Variables\n\nCopy the example environment file and configure it:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` file with your configuration (see [Environment Variables](#environment-variables) section).\n\n#### Step 5: Start MongoDB\n\nEnsure MongoDB is running on your system:\n\n```bash\n# On Ubuntu/Debian\nsudo systemctl start mongod\n\n# On macOS (with Homebrew)\nbrew services start mongodb-community\n\n# Or run manually\nmongod --dbpath /path/to/your/data/directory\n```\n\n#### Step 6: Run the Backend API Server\n\n```bash\n# From the backend-api directory\npython -m app.main\n\n# Or using uvicorn directly\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\nThe backend API server will start on `http://localhost:8000`\n\nYou can access the interactive API documentation at:\n- Swagger UI: `http://localhost:8000/docs`\n- ReDoc: `http://localhost:8000/redoc`\n\n### 3. ML Service Setup\n\n#### Step 1: Navigate to ML Service Directory\n\n```bash\ncd server/ml-service\n```\n\n#### Step 2: Create and Activate Virtual Environment\n\n**On Windows:**\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\n```\n\n**On macOS/Linux:**\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n#### Step 3: Install Dependencies\n\n```bash\npip install --upgrade pip\npip install -r requirements.txt\n```\n\n**Note**: Installing `mediapipe` and `opencv-python-headless` may take several minutes. Ensure you have build tools installed if compilation is required.\n\n**For Ubuntu/Debian:**\n```bash\nsudo apt-get update\nsudo apt-get install build-essential cmake python3-dev\n```\n\n**For macOS:**\n```bash\nbrew install cmake\n```\n\n#### Step 4: Setup Environment Variables\n\nCopy the example environment file and configure it:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` file with your configuration.\n\n#### Step 5: Run the ML Service Server\n\n```bash\n# From the ml-service directory\npython -m app.main\n\n# Or using uvicorn directly\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8001\n```\n\nThe ML service will start on `http://localhost:8001`\n\nYou can access the interactive API documentation at:\n- Swagger UI: `http://localhost:8001/docs`\n- ReDoc: `http://localhost:8001/redoc`\n\n### 4. Frontend Setup\n\nOpen a new terminal window:\n\n#### Step 1: Navigate to Frontend Directory\n\n```bash\ncd frontend\n```\n\n#### Step 2: Install Dependencies\n\n```bash\nnpm install\n```\n\nIf you encounter any issues, try:\n```bash\nnpm install --legacy-peer-deps\n```\n\n#### Step 3: Start Development Server\n\n```bash\nnpm run dev\n```\n\nThe frontend application will start on `http://localhost:5173`\n\n#### Step 4: Build for Production (Optional)\n\n```bash\nnpm run build\nnpm run preview\n```\n\n### Environment Variables\n\n#### Backend API (.env)\n\nCreate a `.env` file in the `server/backend-api` directory with the following variables:\n\n```env\n# MongoDB Configuration\nMONGO_URI=mongodb://localhost:27017\nMONGO_DB=smart_attendance\n\n# JWT Configuration\nJWT_SECRET=your-secret-key-here  # Generate with: python -c \"import secrets; print(secrets.token_urlsafe(32))\"\nJWT_ALGORITHM=HS256\nJWT_EXPIRES_MINUTES=60\n\n# Session Configuration\nSESSION_SECRET_KEY=your-secret-key-here  # Generate with: python -c \"import secrets; print(secrets.token_urlsafe(32))\"\n\n# Email Configuration (for notifications)\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USER=your-email@gmail.com\nSMTP_PASS=your-app-specific-password\nBACKEND_BASE_URL=http://127.0.0.1:8000\nFRONTEND_BASE_URL=http://localhost:5173\n\n# Google OAuth Configuration\nGOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=your-google-client-secret\nGOOGLE_REDIRECT_URI=http://127.0.0.1:8000/auth/google/callback\n\n# Cloudinary Configuration (for image storage)\nCLOUDINARY_CLOUD_NAME=your-cloudinary-cloud-name\nCLOUDINARY_API_KEY=your-cloudinary-api-key\nCLOUDINARY_API_SECRET=your-cloudinary-api-secret\n\n# Demo User Credentials (for testing)\nTEACHER_EMAIL=teacher@gmail.com\nTEACHER_PASSWORD=teacher123\nSTUDENT_EMAIL=student@gmail.com\nSTUDENT_PASSWORD=student123\n```\n\n#### ML Service (.env)\n\nCreate a `.env` file in the `server/ml-service` directory with the following variables:\n\n```env\n# Service Configuration\nML_SERVICE_HOST=0.0.0.0\nML_SERVICE_PORT=8001\n\n# Backend API URL (for communication)\nBACKEND_API_URL=http://localhost:8000\n\n# Model Configuration (if needed)\n# Add any ML model specific configurations here\n```\n\n#### Important Notes:\n\n1. **JWT_SECRET**: Generate a strong random secret:\n   ```bash\n   python -c \"import secrets; print(secrets.token_urlsafe(32))\"\n   ```\n\n2. **Google OAuth**: \n   - Create a project in [Google Cloud Console](https://console.cloud.google.com/)\n   - Enable Google+ API\n   - Create OAuth 2.0 credentials\n   - Add authorized redirect URIs\n\n3. **Gmail SMTP**: \n   - Enable 2-factor authentication on your Gmail account\n   - Generate an [App Password](https://myaccount.google.com/apppasswords)\n   - Use the app password in `SMTP_PASS`\n\n4. **Cloudinary**:\n   - Sign up at [Cloudinary](https://cloudinary.com/)\n   - Get your credentials from the dashboard\n\n---\n\n## 💻 Usage\n\n### For Teachers\n\n#### 1. Login/Register\n\n- Navigate to `http://localhost:5173`\n- Click **\"Login\"** or **\"Register\"**\n- Sign in with Google OAuth or use email/password\n- Select **\"Teacher\"** role during registration\n\n#### 2. Dashboard Overview\n\nAfter logging in, you'll see:\n- **Total Students**: Number of students across all subjects\n- **Today's Attendance**: Attendance marked today\n- **Average Attendance**: Overall attendance percentage\n- **At-Risk Students**: Students with attendance \u003c 75%\n- **Recent Activity**: Latest attendance records\n\n#### 3. Managing Subjects\n\n- Navigate to **Settings** → **Subjects**\n- Click **\"Add Subject\"** to create a new subject\n- Add subject name, code, and schedule\n- Enroll students in subjects\n\n#### 4. Adding Students\n\n- Go to **\"Add Students\"** page\n- Enter student details (name, email, roll number)\n- Upload student photo for facial recognition\n- Click **\"Submit\"** to add the student\n- Students will receive an email invitation\n\n#### 5. Marking Attendance\n\n- Navigate to **\"Mark Attendance\"**\n- Select the subject from dropdown\n- Click **\"Start Camera\"** and allow camera access\n- Position students in front of the camera\n- Click **\"Capture Photo\"**\n- Click **\"Mark Attendance\"**\n- System will:\n  - Detect faces in the image\n  - Match faces with enrolled students\n  - Mark attendance automatically\n  - Show results with confidence scores\n\n#### 6. Viewing Analytics\n\n- Navigate to **\"Analytics\"** page\n- View:\n  - Daily attendance trends\n  - Subject-wise attendance comparison\n  - Monthly attendance heatmap\n  - Student performance charts\n\n#### 7. Generating Reports\n\n- Go to **\"Reports\"** page\n- Select date range\n- Choose subject or all subjects\n- Click **\"Generate Report\"**\n- Export as PDF or CSV\n\n#### 8. Settings \u0026 Preferences\n\n- Navigate to **\"Settings\"**\n- Update profile information\n- Configure email notification preferences\n- Set attendance threshold for alerts\n- Manage subject and class settings\n\n### For Students\n\n#### 1. Login/Register\n\n- Navigate to `http://localhost:5173`\n- Click **\"Login\"** or **\"Register\"**\n- Sign in with Google OAuth or use email/password\n- Select **\"Student\"** role during registration\n\n#### 2. Student Dashboard\n\nAfter logging in, view:\n- **Overall Attendance**: Your attendance percentage\n- **Subject-wise Attendance**: Attendance in each subject\n- **Recent Classes**: Latest attendance records\n- **Alerts**: Low attendance warnings\n\n#### 3. View Subjects\n\n- Navigate to **\"Subjects\"**\n- See all enrolled subjects\n- View attendance percentage per subject\n- Check class schedule and timings\n\n#### 4. Attendance Forecast\n\n- Go to **\"Forecast\"** page\n- View predicted attendance trends\n- See required classes to maintain target percentage\n- Plan accordingly to avoid low attendance\n\n#### 5. Profile Management\n\n- Navigate to **\"Profile\"**\n- Update personal information\n- Change profile picture\n- View enrollment details\n\n---\n\n## 🐳 Docker Deployment\n\n### Using Docker Compose (Recommended)\n\nCreate a `docker-compose.yml` file in the root directory:\n\n```yaml\nversion: '3.8'\n\nservices:\n  mongodb:\n    image: mongo:latest\n    container_name: smart-attendance-mongodb\n    ports:\n      - \"27017:27017\"\n    volumes:\n      - mongodb_data:/data/db\n    environment:\n      MONGO_INITDB_DATABASE: smart_attendance\n\n  backend:\n    build: ./backend\n    container_name: smart-attendance-backend\n    ports:\n      - \"8000:8000\"\n    depends_on:\n      - mongodb\n    environment:\n      MONGO_URI: mongodb://mongodb:27017\n      MONGO_DB: smart_attendance\n    env_file:\n      - ./backend/.env\n    volumes:\n      - ./backend:/app\n\n  frontend:\n    build: ./frontend\n    container_name: smart-attendance-frontend\n    ports:\n      - \"5173:5173\"\n    depends_on:\n      - backend\n    environment:\n      VITE_API_URL: http://localhost:8000\n\nvolumes:\n  mongodb_data:\n```\n\n#### Run with Docker Compose\n\n```bash\n# Build and start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop all services\ndocker-compose down\n\n# Stop and remove volumes\ndocker-compose down -v\n```\n\n### Using Individual Docker Commands\n\n#### Backend\n\n```bash\ncd backend\ndocker build -t smart-attendance-backend .\ndocker run -p 8000:8000 --env-file .env smart-attendance-backend\n```\n\n#### Frontend\n\n```bash\ncd frontend\ndocker build -t smart-attendance-frontend .\ndocker run -p 5173:5173 smart-attendance-frontend\n```\n\n---\n\n## 📁 Project Structure\n\n```\nsmart-attendance/\n├── server/                             # Backend services\n│   ├── backend-api/                    # Backend API server\n│   │   ├── app/\n│   │   │   ├── api/                    # API routes\n│   │   │   │   ├── routes/\n│   │   │   │   │   ├── auth.py         # Authentication endpoints\n│   │   │   │   │   ├── students.py     # Student management\n│   │   │   │   │   ├── attendance.py   # Attendance marking\n│   │   │   │   │   └── teacher_settings.py # Teacher preferences\n│   │   │   │   └── deps.py             # API dependencies\n│   │   │   ├── core/                   # Core configuration\n│   │   │   │   ├── config.py           # App configuration\n│   │   │   │   ├── security.py         # Security utilities\n│   │   │   │   ├── email.py            # Email service\n│   │   │   │   └── cloudinary_config.py # Cloud storage config\n│   │   │   ├── db/                     # Database layer\n│   │   │   │   ├── mongo.py            # MongoDB connection\n│   │   │   │   ├── models.py           # Database models\n│   │   │   │   ├── base.py             # Base repository\n│   │   │   │   ├── session.py          # Session management\n│   │   │   │   ├── subjects_repo.py    # Subject repository\n│   │   │   │   └── teacher_settings_repo.py\n│   │   │   ├── schemas/                # Pydantic schemas\n│   │   │   │   ├── user.py             # User schemas\n│   │   │   │   ├── student.py          # Student schemas\n│   │   │   │   ├── teacher.py          # Teacher schemas\n│   │   │   │   ├── auth.py             # Authentication schemas\n│   │   │   │   ├── attendance.py       # Attendance schemas\n│   │   │   │   ├── timetable.py        # Timetable schemas\n│   │   │   │   └── teacher_settings.py # Settings schemas\n│   │   │   ├── services/               # Business logic\n│   │   │   │   ├── attendance.py       # Attendance logic\n│   │   │   │   ├── students.py         # Student management\n│   │   │   │   ├── subject_service.py  # Subject management\n│   │   │   │   ├── email.py            # Email service\n│   │   │   │   └── teacher_settings_service.py\n│   │   │   ├── utils/                  # Utility functions\n│   │   │   │   ├── jwt_token.py        # JWT utilities\n│   │   │   │   ├── logging.py          # Logging configuration\n│   │   │   │   └── utils.py            # General utilities\n│   │   │   └── main.py                 # Application entry point\n│   │   ├── tests/                      # Test suite\n│   │   ├── .env.example                # Environment variables template\n│   │   ├── Dockerfile                  # Docker configuration\n│   │   └── requirements.txt            # Python dependencies\n│   │\n│   └── ml-service/                     # ML facial recognition service\n│       ├── app/\n│       │   ├── api/                    # API routes\n│       │   │   ├── routes/\n│       │   │   │   └── face.py         # Face detection endpoints\n│       │   │   └── deps.py             # API dependencies\n│       │   ├── core/                   # Core configuration\n│       │   │   └── config.py           # App configuration\n│       │   ├── ml/                     # ML models and logic\n│       │   │   ├── face_detection.py   # Face detection using MediaPipe\n│       │   │   ├── face_encoding.py    # Face encoding\n│       │   │   └── face_matching.py    # Face matching logic\n│       │   ├── schemas/                # Pydantic schemas\n│       │   │   └── face.py             # Face data schemas\n│       │   ├── utils/                  # Utility functions\n│       │   │   ├── image.py            # Image processing\n│       │   │   └── utils.py            # General utilities\n│       │   └── main.py                 # Application entry point\n│       ├── .env.example                # Environment variables template\n│       ├── Dockerfile                  # Docker configuration\n│       └── requirements.txt            # Python dependencies\n│\n├── frontend/                           # Frontend React application\n│   ├── public/                         # Public assets\n│   │   ├── logo.png\n│   │   └── logo-bg.png\n│   ├── src/\n│   │   ├── api/                        # API client\n│   │   │   └── axios.js                # Axios configuration\n│   │   ├── assets/                     # Images and resources\n│   │   ├── components/                 # Reusable components\n│   │   │   ├── Header.jsx              # Navigation header\n│   │   │   └── ...\n│   │   ├── hooks/                      # Custom React hooks\n│   │   ├── pages/                      # Page components\n│   │   │   ├── Dashboard.jsx           # Teacher dashboard\n│   │   │   ├── Login.jsx               # Login page\n│   │   │   ├── Register.jsx            # Registration page\n│   │   │   ├── MarkAttendance.jsx      # Attendance marking\n│   │   │   ├── StudentList.jsx         # Student listing\n│   │   │   ├── AddStudents.jsx         # Add students\n│   │   │   ├── Analytics.jsx           # Analytics page\n│   │   │   ├── Reports.jsx             # Reports generation\n│   │   │   ├── Settings.jsx            # Settings page\n│   │   │   └── OAuthCallback.jsx       # OAuth callback\n│   │   ├── students/                   # Student portal\n│   │   │   └── pages/\n│   │   │       ├── StudentDashboard.jsx\n│   │   │       ├── StudentSubjects.jsx\n│   │   │       ├── StudentForecast.jsx\n│   │   │       └── StudentProfile.jsx\n│   │   ├── renderer/                   # UI renderers\n│   │   ├── theme/                      # Theme configuration\n│   │   │   └── ThemeContext.jsx\n│   │   ├── App.jsx                     # Main app component\n│   │   ├── main.jsx                    # Application entry\n│   │   └── index.css                   # Global styles\n│   ├── .gitignore\n│   ├── index.html\n│   ├── package.json                    # NPM dependencies\n│   ├── package-lock.json\n│   ├── vite.config.js                  # Vite configuration\n│   ├── eslint.config.js                # ESLint configuration\n│   ├── postcss.config.js               # PostCSS configuration\n│   └── vercel.json                     # Vercel deployment config\n│\n├── .github/                            # GitHub configuration\n│   ├── ISSUE_TEMPLATE/\n│   │   ├── bug_report.md\n│   │   └── feature_request.md\n│   └── pull_request_template.md\n├── .gitignore                          # Git ignore rules\n├── CODE_OF_CONDUCT.md                  # Code of conduct\n├── CONTRIBUTING.md                     # Contribution guidelines\n├── README.md                           # This file\n└── learn.md                            # Beginner's guide\n```\n\n---\n\n## 📡 API Documentation\n\n### Base URL\n```\nhttp://localhost:8000\n```\n\n### Interactive Documentation\n- **Swagger UI**: `http://localhost:8000/docs`\n- **ReDoc**: `http://localhost:8000/redoc`\n\n### Authentication\n\nAll protected endpoints require a JWT token in the Authorization header:\n```\nAuthorization: Bearer \u003cyour-jwt-token\u003e\n```\n\n### API Endpoints\n\n#### Authentication\n\n##### Register User\n```http\nPOST /api/auth/register\nContent-Type: application/json\n\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"securepassword\",\n  \"name\": \"John Doe\",\n  \"role\": \"teacher\"  // or \"student\"\n}\n```\n\n##### Login\n```http\nPOST /api/auth/login\nContent-Type: application/json\n\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"securepassword\"\n}\n```\n\n**Response:**\n```json\n{\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n  \"token_type\": \"bearer\",\n  \"user\": {\n    \"id\": \"507f1f77bcf86cd799439011\",\n    \"email\": \"user@example.com\",\n    \"name\": \"John Doe\",\n    \"role\": \"teacher\"\n  }\n}\n```\n\n##### Google OAuth Login\n```http\nGET /auth/google/login\n```\nRedirects to Google OAuth consent screen.\n\n##### Google OAuth Callback\n```http\nGET /auth/google/callback?code=\u003cauthorization-code\u003e\n```\n\n#### Students\n\n##### Get All Students\n```http\nGET /api/students\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n**Response:**\n```json\n[\n  {\n    \"_id\": \"507f1f77bcf86cd799439011\",\n    \"name\": \"Ravi Kumar\",\n    \"email\": \"ravi@example.com\",\n    \"roll_number\": \"2101\",\n    \"profile_image\": \"https://cloudinary.com/...\",\n    \"attendance_percentage\": 85.5\n  }\n]\n```\n\n##### Add Student\n```http\nPOST /api/students\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: multipart/form-data\n\n{\n  \"name\": \"New Student\",\n  \"email\": \"student@example.com\",\n  \"roll_number\": \"2150\",\n  \"photo\": \u003cfile\u003e\n}\n```\n\n##### Get Student Details\n```http\nGET /api/students/{student_id}\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n#### Attendance\n\n##### Mark Attendance\n```http\nPOST /api/attendance/mark\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"image\": \"data:image/jpeg;base64,/9j/4AAQSkZJRg...\",\n  \"subject_id\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"detected\": [\n    {\n      \"student_id\": \"507f1f77bcf86cd799439011\",\n      \"name\": \"Ravi Kumar\",\n      \"roll_number\": \"2101\",\n      \"confidence\": 0.95,\n      \"status\": \"present\"\n    }\n  ],\n  \"not_detected\": [\n    {\n      \"student_id\": \"507f1f77bcf86cd799439012\",\n      \"name\": \"Priya Singh\",\n      \"roll_number\": \"2102\"\n    }\n  ],\n  \"count\": 1,\n  \"timestamp\": \"2025-01-15T10:30:00\"\n}\n```\n\n##### Get Attendance Records\n```http\nGET /api/attendance?subject_id={id}\u0026date={YYYY-MM-DD}\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n##### Get Student Attendance\n```http\nGET /api/attendance/student/{student_id}\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n#### Subjects/Classes\n\n##### Get All Subjects\n```http\nGET /api/classes\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n##### Create Subject\n```http\nPOST /api/classes\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"Data Structures\",\n  \"code\": \"CS201\",\n  \"students\": [\"507f1f77bcf86cd799439011\"]\n}\n```\n\n##### Get Subject Details\n```http\nGET /api/classes/{subject_id}\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n#### Face Recognition\n\n##### Upload Student Face\n```http\nPOST /api/face/upload\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: multipart/form-data\n\n{\n  \"student_id\": \"507f1f77bcf86cd799439011\",\n  \"image\": \u003cfile\u003e\n}\n```\n\n##### Verify Face\n```http\nPOST /api/face/verify\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"student_id\": \"507f1f77bcf86cd799439011\",\n  \"image\": \"data:image/jpeg;base64,...\"\n}\n```\n\n#### Teacher Settings\n\n##### Get Settings\n```http\nGET /api/teacher-settings\nAuthorization: Bearer \u003ctoken\u003e\n```\n\n##### Update Settings\n```http\nPUT /api/teacher-settings\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"email_notifications\": true,\n  \"attendance_threshold\": 75,\n  \"notification_time\": \"09:00\"\n}\n```\n\n### Error Responses\n\n#### 400 Bad Request\n```json\n{\n  \"detail\": \"Invalid request parameters\"\n}\n```\n\n#### 401 Unauthorized\n```json\n{\n  \"detail\": \"Could not validate credentials\"\n}\n```\n\n#### 404 Not Found\n```json\n{\n  \"detail\": \"Resource not found\"\n}\n```\n\n#### 500 Internal Server Error\n```json\n{\n  \"detail\": \"Internal server error\"\n}\n```\n\n---\n\n## 📸 Screenshots\n\n### Teacher Dashboard\n\u003cimg width=\"1891\" height=\"1025\" alt=\"image\" src=\"https://github.com/user-attachments/assets/3a75afd6-b8b0-4f49-af2f-f9cb28cfeb18\" /\u003e\n*Comprehensive overview of attendance statistics and analytics*\n\n### Mark Attendance\n\u003cimg width=\"1894\" height=\"1029\" alt=\"image\" src=\"https://github.com/user-attachments/assets/1c82ad55-00d1-42ca-adb2-9f4506f53cb7\" /\u003e\n*Real-time facial recognition attendance marking*\n\n### Student List\n\u003cimg width=\"1900\" height=\"1032\" alt=\"image\" src=\"https://github.com/user-attachments/assets/12aaa1ed-bd6a-49c2-a623-d2682a79aa74\" /\u003e\n*Manage and view all enrolled students*\n\n### Analytics\n\u003cimg width=\"1900\" height=\"1033\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9856f3eb-37aa-496b-82f2-a7d34a79796b\" /\u003e\n*Detailed attendance analytics and reports*\n\n### Student Dashboard\n\u003cimg width=\"1895\" height=\"1025\" alt=\"image\" src=\"https://github.com/user-attachments/assets/222dc04f-d448-4a35-b70e-07be20ab283d\" /\u003e\n*Student portal with attendance overview*\n\n---\n\n## 🤝 Contributing\n\nWe love contributions! Smart Attendance is an open-source project and we welcome contributions from developers of all skill levels. Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.\n\n### How to Contribute\n\nPlease read our [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines on:\n- Code of Conduct\n- Setting up your development environment\n- Making changes and creating pull requests\n- Coding standards and best practices\n\n### Quick Start for Contributors\n\n1. **Fork the repository**\n   ```bash\n   # Click the 'Fork' button on GitHub\n   ```\n\n2. **Clone your fork**\n   ```bash\n   git clone https://github.com/YOUR-USERNAME/smart-attendance.git\n   cd smart-attendance\n   ```\n\n3. **Create a branch**\n   ```bash\n   git checkout -b feature/your-feature-name\n   # or\n   git checkout -b fix/your-bug-fix\n   ```\n\n4. **Make your changes**\n   - Write clean, well-documented code\n   - Follow existing code style\n   - Add tests if applicable\n   - Update documentation\n\n5. **Commit your changes**\n   ```bash\n   git add .\n   git commit -m \"feat: add amazing feature\"\n   # or\n   git commit -m \"fix: resolve bug in attendance marking\"\n   ```\n\n6. **Push to your fork**\n   ```bash\n   git push origin feature/your-feature-name\n   ```\n\n7. **Create a Pull Request**\n   - Go to the original repository\n   - Click \"New Pull Request\"\n   - Select your branch\n   - Fill in the PR template\n   - Submit!\n\n### Contribution Areas\n\n- 🐛 **Bug Fixes**: Found a bug? Fix it!\n- ✨ **New Features**: Have an idea? Implement it!\n- 📝 **Documentation**: Improve README, add tutorials\n- 🎨 **UI/UX**: Enhance the user interface\n- 🧪 **Testing**: Add unit tests, integration tests\n- ♿ **Accessibility**: Make the app more accessible\n- 🌐 **Internationalization**: Add multi-language support\n- ⚡ **Performance**: Optimize code for better performance\n\n### Development Guidelines\n\n- Follow **PEP 8** for Python code\n- Use **ESLint** for JavaScript/React code\n- Write **meaningful commit messages**\n- Add **comments** for complex logic\n- Update **documentation** for new features\n- **Test your changes** thoroughly\n- Keep PRs **focused and small**\n\n### Community\n\n- 📢 **Discussions**: Join GitHub Discussions\n- 🐛 **Issues**: Report bugs or request features\n- 💬 **Discord**: Join our community server (coming soon)\n- 📧 **Email**: Contact maintainers for questions\n\n---\n\n## 🔒 Security\n\n### Security Best Practices\n\nSmart Attendance implements several security measures:\n\n✅ **Implemented:**\n- JWT-based authentication\n- OAuth 2.0 integration with Google\n- Password hashing with bcrypt\n- CORS protection\n- Session management\n- Input validation with Pydantic\n- Secure environment variable storage\n- HTTPS support (in production)\n\n⚠️ **Important Notes:**\n\n1. **Never commit sensitive data** to version control\n   - Use `.env` files for secrets\n   - Add `.env` to `.gitignore`\n   - Use environment variables in production\n\n2. **Production Deployment:**\n   - Change all default secrets and keys\n   - Use strong, randomly generated passwords\n   - Enable HTTPS/TLS\n   - Set `https_only=True` in SessionMiddleware\n   - Use secure MongoDB connection strings\n   - Implement rate limiting\n   - Add CSRF protection\n   - Use security headers (Helmet.js equivalent)\n\n3. **Database Security:**\n   - Use MongoDB authentication\n   - Restrict database access to backend only\n   - Regular backups\n   - Encrypt sensitive data at rest\n\n4. **Face Recognition Data:**\n   - Face embeddings are stored securely\n   - Images are processed and discarded (not stored permanently)\n   - Profile pictures stored on Cloudinary with access control\n\n### Reporting Security Vulnerabilities\n\nIf you discover a security vulnerability, please:\n\n1. **Do NOT** open a public issue\n2. Email the maintainers privately\n3. Provide detailed information about the vulnerability\n4. Allow time for a fix before public disclosure\n\nWe take security seriously and will respond promptly to all reports.\n\n---\n\n## 🗺️ Roadmap\n\n### Version 1.0 (Current)\n- [x] Basic facial recognition attendance\n- [x] Teacher and student dashboards\n- [x] MongoDB integration\n- [x] Google OAuth login\n- [x] Subject management\n\n\n### Version 1.1 (In Progress)\n- [ ] Attendance analytics\n- [ ] Email notifications\n- [ ] Reports generation\n- [ ] Attendance geofencing\n- [ ] QR code backup attendance\n- [ ] Multi-language support\n\n### Version 2.0 (Planned)\n- [ ] Video-based attendance (process video feed)\n- [ ] Biometric integration\n- [ ] Parent portal\n- [ ] Mobile notifications (Push)\n- [ ] Offline mode support\n\n### Version 3.0 (Future)\n- [ ] Multi-institution support\n- [ ] API marketplace for third-party integrations\n- [ ] Blockchain-based attendance records\n- [ ] Advanced fraud detection\n- [ ] Virtual/Remote class support with Zoom/Meet integration\n\n### Community Requested Features\n- Custom attendance policies per subject\n- Proxy detection using advanced AI\n- Attendance appeals/corrections workflow\n- Integration with ID card systems\n- Exam hall attendance mode\n- Leave management system\n\nWant to contribute to any of these? Check out our [issues](https://github.com/nem-web/smart-attendance/issues) page!\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n```\nMIT License\n\nCopyright (c) 2025 nem-web\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n---\n\n## 📞 Support\n\n### Get Help\n\nIf you need help or have questions:\n\n- 📖 **Documentation**: Read this README and [learn.md](./learn.md)\n- 🐛 **Bug Reports**: [Open an issue](https://github.com/nem-web/smart-attendance/issues/new?template=bug_report.md)\n- 💡 **Feature Requests**: [Request a feature](https://github.com/nem-web/smart-attendance/issues/new)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/nem-web/smart-attendance/discussions)\n- 📧 **Email**: Contact the maintainers\n- 🌐 **Community**: Join our Discord server (coming soon)\n\n### FAQ\n\n**Q: Does this work on mobile devices?**  \nA: Yes! The web app is fully responsive and works on mobile browsers.\n\n**Q: Can I use this for my school/college?**  \nA: Absolutely! This is open-source software. Just follow the installation guide.\n\n**Q: Is facial recognition accurate?**  \nA: The system uses MediaPipe for face detection with high accuracy. However, lighting and camera quality affect results.\n\n**Q: Do I need a GPU for face recognition?**  \nA: No, CPU is sufficient for small-scale deployments. GPU recommended for 100+ students.\n\n**Q: Can I customize the attendance threshold?**  \nA: Yes, teachers can set custom thresholds in Settings.\n\n**Q: Is the data secure?**  \nA: Yes, we use industry-standard security practices. See the [Security](#-security) section.\n\n---\n\n## 👥 Authors\n\n### Main Contributors\n\n- **nem-web** - *Project Creator \u0026 Lead Developer* - [GitHub](https://github.com/nem-web)\n\n### Contributors\n\nA big thank you to all our contributors! 🎉\n\n[![Contributors](https://contrib.rocks/image?repo=nem-web/smart-attendance)](https://github.com/nem-web/smart-attendance/graphs/contributors)\n\nWant to see your name here? Check out our [Contributing Guide](#-contributing)!\n\n---\n\n## 🙏 Acknowledgments\n\nSpecial thanks to:\n\n- **FastAPI** team for the amazing framework\n- **React** team for the powerful UI library\n- **MediaPipe** team for the face detection library\n- All our **open-source contributors**\n- Educational institutions testing this system\n- The **open-source community** for invaluable feedback\n\n### Built With Love Using\n\n- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework\n- [React](https://react.dev/) - JavaScript library for user interfaces\n- [MongoDB](https://www.mongodb.com/) - NoSQL database\n- [MediaPipe](https://google.github.io/mediapipe/) - Face detection and analysis\n- [OpenCV](https://opencv.org/) - Computer vision library\n- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework\n- [Vite](https://vitejs.dev/) - Next-generation frontend tooling\n- [Cloudinary](https://cloudinary.com/) - Media management platform\n\n---\n\n## 🌐 Live Demo\n\n### Try It Out\n\n- **Frontend Demo**: [https://studentcheck.vercel.app](https://studentcheck.vercel.app)\n- **UI Design Preview**: [https://app.banani.co/preview/n08pleRdJIZY](https://app.banani.co/preview/n08pleRdJIZY)\n- **API Documentation**: Available at `/docs` endpoint when running locally\n\n### Demo Credentials\n\n```\nTeacher Account:\nEmail: teacher@gmail.com\nPassword: teacher123\n\nStudent Account:\nEmail: student@gmail.com\nPassword: student123\n```\n\n**Note**: Demo deployment may have limited features. For full functionality, run locally.\n\n---\n\n## 🌟 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=nem-web/smart-attendance\u0026type=Date)](https://star-history.com/#nem-web/smart-attendance\u0026Date)\n\n---\n\n## 📊 Project Stats\n\n![GitHub repo size](https://img.shields.io/github/repo-size/nem-web/smart-attendance)\n![GitHub language count](https://img.shields.io/github/languages/count/nem-web/smart-attendance)\n![GitHub top language](https://img.shields.io/github/languages/top/nem-web/smart-attendance)\n![GitHub last commit](https://img.shields.io/github/last-commit/nem-web/smart-attendance)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/nem-web/smart-attendance)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### ⭐ Star this repository if you find it helpful!\n\n**Made with ❤️ for better education management**\n\n[Report Bug](https://github.com/nem-web/smart-attendance/issues) · [Request Feature](https://github.com/nem-web/smart-attendance/issues) · [Contribute](./CONTRIBUTING.md)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnem-web%2Fsmart-attendance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnem-web%2Fsmart-attendance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnem-web%2Fsmart-attendance/lists"}