Smart School Attendance System

Dashboard View

A full-stack, NFC-enabled attendance management system for schools, built with FastAPI (backend/API), SQLite (database), React + Tailwind CSS (frontend dashboard), and ESP8266/ESP32/Arduino (hardware integration).

Features

• 💳 NFC/RFID-based student authentication and attendance marking.
• 🚀 Real-time dashboard: see live attendance, class stats, recent scans, and percentages.
• 📦 FastAPI async backend with SQLite—easy to set up, lightweight, production-ready.
• 🖥️ Exhibition-ready, visually appealing frontend with live animations, attractive stats cards and class-wise breakdowns.
• 📱 WiFi-enabled hardware integration: ESP8266/ESP32 reads cards and sends data instantly to the server.
• 🔒 Safe to use in schools—no sensitive personal data transmitted from cards.

Architecture Overview

graph TD
    ESP8266/ESP32/Arduino -.-> FastAPI API (POST /register, /mark)
    FastAPI --> SQLite Database
    FastAPI --> React Dashboard (REST: /api/)
    Users --> React Dashboard

Loading

Hardware Requirements

• ESP8266 NodeMCU or ESP32 board
• MFRC522 RFID/NFC module
• LEDs (Red, Green, Blue) and buzzer for feedback
• Push button for mode switch (Write/Read)
• NFC/MIFARE Classic cards

Backend: FastAPI + SQLite

• Install dependencies:
  pip install -r requirements.txt

• Run server:
  python main.py

• Endpoints:

  • /api/students/register - Register student & card
  • /api/attendance/mark - Mark attendance
  • /api/students - List students
  • /api/attendance/today - Today's attendance
  • /api/dashboard/stats - Summary stats
  • /api/dashboard/class-wise - Per-class stats

Frontend Dashboard

• Location: frontend/
• Access: Open http://localhost:8000 in browser.
• Live updates: Visual feedback and scan animation for new entries.

Arduino/ESP Code

• Hardware: Use ESP8266 NodeMCU or ESP32.
• Libraries: MFRC522, ArduinoJson, ESP8266WiFi, ESP8266HTTPClient (or corresponding for ESP32)
• Modes:
  • Write Mode: Register/program student card, send data to server (/register)
  • Read Mode: Scan card, authenticate on server, mark attendance (/mark)
• Configuration:
  • Set WiFi SSID/PASSWORD and server URL in sketch before upload

Testing

• Comprehensive test script:
  python tests/test_system.py

• Quick test:
  python tests/quick_test.py

Example Workflow

1. Power ESP board — Green LED = Attendance mode (default)
2. Press button — Blue LED = Write mode; program card & register student
3. Scan card in attendance mode — Card data sent to FastAPI for authentication; attendance marked if valid
4. Dashboard — See stats and recent activity, refreshed instantly

Folder Structure

smart-attendance-system-with-arduino/
├── main.py
├── models.py
├── database.py
├── requirements.txt
└── arduino/
    ├── main.cc
└── tests/
    ├── main_test.py
    ├── quick_test.py
└── frontend/
    ├── index.html
    ├── styles.css
    └── app.js

Deployment

• Clone repository
• Create Python venv and install dependencies
• Start FastAPI server: python main.py
• Open in browser: http://localhost:8000
• Upload ESP code to hardware, connect to same WiFi

License

MIT License

---

See [FastAPI documentation](https://fastapi.tiangolo.com/) for backend customization tips.