RFID Access Control API v2.0

Modular Flask API for RFID access control with ESP32 integration.

Layered architecture: API → Services → Repositories → Models

---

🚀 Quick Start

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env

# Database will be auto-created on first run at instance/access_control.db
# To reset database in development: delete instance/access_control.db

# Create admin user
python scripts/init_admin.py

# Run development server
python run.py

API: http://localhost:5000/api

---

📁 Structure

src/
├── api/          # Endpoints (auth, users, cards, events, stats, export, health)
├── services/     # Business logic
├── repositories/ # Data access
├── models/       # SQLAlchemy models
├── schemas/      # Pydantic validation
├── middleware/   # Auth & dependencies
└── core/         # Config, database, exceptions

scripts/          # init_admin.py, manage_cards.py
tests/            # Unit + integration tests

---

📖 Documentation

• API Reference: API.md - All endpoints

---

🧪 Testing

pytest                    # All tests
pytest --cov=src          # With coverage

---

🛠️ CLI Scripts

Admin & Card Management

# Create admin user
python scripts/init_admin.py

# Manage cards
python scripts/manage_cards.py list
python scripts/manage_cards.py add UID "Name"
python scripts/manage_cards.py enable UID
python scripts/manage_cards.py disable UID

Development Database Reset

# Reset database (development only)
rm instance/access_control.db  # Linux/Mac
del instance\access_control.db  # Windows

# Then run the app to recreate with current schema
python run.py

---

🔐 Auth

JWT (Web): Authorization: Bearer <token> - Get from POST /api/auth/login
API Key (ESP32): Authorization: Bearer <api_key> - Set in .env

Roles: admin (full), operator (cards), supervisor (read-only)

---

🏗️ Architecture

Request → API → Middleware → Services → Repositories → Models → Database

Benefits: Testable, scalable, maintainable, modular

---

Stack: Flask 3.0 · SQLAlchemy 2.0 · Pydantic 2.6 · pytest