🔐 LockNet - Smart Lock Management System

LockNet is a complete IoT platform for managing RFID access control systems. It provides a web dashboard, REST API, and ESP32 firmware for controlling smart locks and tracking access.

What You Get

• Web Dashboard - Manage users, RFID cards, and view access logs
• REST API - Control everything programmatically
• ESP32 Firmware - RFID reader device code
• Role-Based Access - Admin and user accounts with strict permissions

Project Structure

locknet/
├── backend/              FastAPI REST API
│   ├── alembic/         Database migrations
│   ├── models/          Database models (User, RFIDCard, AccessLog)
│   ├── routers/         API endpoints (auth, rfid, access, users)
│   ├── schemas/         Request/response validation
│   ├── utils/           Helper functions (auth, validation)
│   ├── scripts/         Utility scripts (create_admin.py, init_db.py)
│   ├── main.py          Application entry point
│   └── create_tables.py Database initialization
│
├── frontend/            React + TypeScript dashboard
│   └── src/
│       ├── components/  Reusable UI (Button, Table, Modal, etc.)
│       ├── pages/       Page components (Dashboard, Users, etc.)
│       ├── services/    API client functions
│       └── types/       TypeScript type definitions
│
└── esp32/               ESP32 RFID reader firmware
    ├── locknet_rfid/    Arduino firmware
    └── rfid_simulator.py Testing tool for card scans

Documentation Index

• QUICK_START.md - Step-by-step setup guide
• SECURITY.md - Security architecture and features
• backend/AUTH.md - Authentication API reference
• backend/RFID_API.md - RFID endpoints documentation
• frontend/DASHBOARD.md - Dashboard features guide
• esp32/README.md - Hardware setup and ESP32 programming

Getting Started

New here? Read QUICK_START.md for a complete walkthrough.

Quick setup (assumes PostgreSQL running):

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set DATABASE_URL and SECRET_KEY
python create_tables.py
python scripts/create_admin.py  # Create admin user
python main.py

# Frontend (new terminal)
cd frontend
npm install
cp .env.example .env
npm run dev

• Backend: http://localhost:8000
• Frontend: http://localhost:5173
• API Docs: http://localhost:8000/docs

Don't have PostgreSQL? See QUICK_START.md for Docker setup.

Key Features

• RFID Access Control - Read and verify RFID cards
• Multi-user - Support for multiple users with role-based access
• Audit Trail - Complete logs of all access attempts
• Admin Dashboard - Manage cards, users, and permissions
• REST API - Full API for integrations
• Security First - Bcrypt passwords, JWT tokens, rate limiting

API Quick Reference

Endpoint	Purpose
POST /auth/login	User login, returns JWT token
POST /auth/register	Register new user
POST /rfid/register	Register RFID card
GET /rfid	List all RFID cards
POST /access/scan	Verify card scan from ESP32
GET /access/logs	View access history

Full documentation at http://localhost:8000/docs when running the backend.

Development

Open two terminal windows:

# Terminal 1: Backend
cd backend && source venv/bin/activate && python main.py

# Terminal 2: Frontend
cd frontend && npm run dev

Then visit http://localhost:5173

Database Operations

Task	Command	When
Create tables (fresh)	python create_tables.py	First time setup
Apply migrations	alembic upgrade head	After pulling updates
Create admin	python scripts/create_admin.py	First admin account
Check DB + migrations	python scripts/init_db.py	Verify setup

Security

LockNet implements multiple security layers:

• Authentication - JWT tokens expire in 30 minutes
• Authorization - Roles enforced on every request from database
• Rate Limiting - Registration endpoints limited to prevent abuse
• Audit Logs - All admin actions logged with timestamps
• Ownership - Users can only access their own resources
• Hashing - Passwords and RFID UIDs hashed with bcrypt

See SECURITY.md for complete security documentation.