Local School Event Attendance

A router-independent, fully offline FastAPI attendance system for school events. Students check in with their first name, last name, and section. The system uses roster matching, duplicate protection, rate limits, local-network presence, and an event-long device/session lock.

For a non-technical overview, feature list, staff instructions, and FAQs, open the easy user guide in any browser.

Quick start

Requires Python 3.11 or newer.

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
python -m scripts.seed_demo
uvicorn app.main:app --host 0.0.0.0 --port 8000

On Linux, activate with source .venv/bin/activate. Open http://localhost:8000/admin and sign in with the seed credentials printed by the seed command. Change the demo password before real use. The student portal is / and asks only for the student’s first name, last name, and section.

Operations

• Import roster CSV from Students. Required columns: student_number,first_name,last_name,program,year_level,section,pin; optional middle_name.
• Create an event and check Assign every active student, or assign all later.
• Export CSV/PDF from Events. PINs are never included.
• Create an online-safe SQLite backup from the dashboard or run python -m scripts.backup from Task Scheduler/cron.
• With Uvicorn stopped, restore a verified repository backup using python -m scripts.restore_backup backups/YYYY-MM-DD/HHMMSS.db --confirm.
• Apply session/IP retention with python -m scripts.prune_sessions.
• Verify a running server with python -m scripts.load_check --requests 1000 --workers 50.
• Run tests with pytest.

Security and limits

Set a random 32+ character ATTENDANCE_SECRET_KEY, use a trusted admin network, block WAN access, and enable ATTENDANCE_SECURE_COOKIES=true only when serving local HTTPS. All timestamps are stored as UTC and rendered in Asia/Manila by default. SQLite uses WAL, foreign keys, a 15-second busy timeout, short transactions, and database uniqueness on (event_id, student_id).

This system deters proxy attendance; it cannot prove physical identity absolutely without staff ID checks, school QR, RFID, NFC, or biometrics. Device/session signals are intentionally defense-in-depth signals, not a claim that IP, cookies, User-Agent, MAC address, or any fingerprint uniquely identifies a person.

Deployment and event procedures are in NETWORK.md, CAPTIVE_PORTAL.md, EVENT_RUNBOOK.md, and DEPLOYMENT.md.