Smart Door: IoT RFID Access Control System

Overview

Smart Door is an enterprise-grade, event-driven RFID access control system built on Pervasive Computing (IoT) principles. The ESP32 on the edge acts as a "dumb sensor" that only reads UHF tags; all business logic lives in a Go backend; a Next.js dashboard provides real-time monitoring and remote control.

The physical world (card taps, door, LEDs) is decoupled from credential validation through an MQTT pub/sub protocol, so the edge device stays simple, secure, and easy to replace. A five-layer pervasive-computing model shapes the whole design:

Tech Stack & Rationale

Architecture

The data flow is a single path from card tap to door action:

1. A UHF tag approaches the reader. The ESP32 parses the EPC frame over RS485 (auto-detecting baud rate), then hashes the raw UID with SHA-256 on-device. The raw UID never leaves the device.
2. The ESP32 publishes a door/scan message to Mosquitto containing uid_hash, device_id, a nonce, and a timestamp.
3. The Go backend subscribes to door/scan. It applies rate limiting (max 1 scan / 2 s per device), rejects replays (nonce de-duplicated for 60 s, timestamp window 30 s), then looks up sha256(rawUID + pepper) in PostgreSQL.
4. The backend publishes a door/command message: status: 1 (green LED + 1 beep) or status: 0 (red LED + 3 beeps). The door is fail-secure: without a validated server response it stays locked.
5. Every decision is written to access_logs, and the dashboard receives the live stream over WebSocket (/api/ws).

An admin can also open or lock the door manually from the dashboard via POST /api/door/override.

Folder Structure

rfid-access-control/
├── apps/
│   ├── firmware/          # ESP32 edge (Arduino / PlatformIO)
│   │   └── src/           # main.cpp, uhf_reader, crypto, mqtt_handler, actuators
│   ├── backend/           # Go: MQTT handler, DB, WebSocket
│   │   ├── cmd/server/main.go
│   │   └── internal/{db,mqtt,ws,crypto,models}
│   └── frontend/          # Next.js 14 dashboard
├── infrastructure/
│   ├── docker-compose.yml        # Postgres + Mosquitto (dev)
│   ├── docker-compose.prod.yml   # full stack (backend + frontend)
│   ├── mosquitto.conf
│   ├── init.sql                  # seed schema
│   └── .env.example
├── docs/
└── package.json                  # root orchestrator (concurrently)

Database Design

CREATE TABLE users (
  id            SERIAL PRIMARY KEY,
  name          VARCHAR(100) NOT NULL,
  rfid_uid_hash VARCHAR(64) UNIQUE NOT NULL,   -- sha256(rawUID + pepper)
  role          VARCHAR(50) DEFAULT 'employee',
  is_active     BOOLEAN DEFAULT TRUE,
  created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE access_logs (
  id            SERIAL PRIMARY KEY,
  rfid_uid_hash VARCHAR(64) NOT NULL,
  status        VARCHAR(20) NOT NULL,           -- AUTHORIZED | DENIED
  action_by     VARCHAR(100),
  device_id     VARCHAR(50),
  timestamp     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

access_logs is write-heavy and grows without bound; it is indexed on (device_id, timestamp DESC), (timestamp DESC), and (status), with periodic retention cleanup expected in production.

Security Model

• UID is hashed on-device (SHA-256) before transmission; the raw UID never enters the network.
• The database stores sha256(rawUID + UID_PEPPER), so a leaked database cannot be reversed into clonable cards.
• Mosquitto requires per-client credentials; anonymous connections are disabled.
• Anti-replay: per-scan nonce (60 s dedup) plus a 30 s timestamp window.
• Per-device rate limiting and a firmware watchdog with Wi-Fi/MQTT exponential backoff.
• MQTT Last Will (LWT) publishes offline automatically if a device disconnects.

Impact & Results

• Academic capstone project demonstrating a production-grade IoT access-control pattern: hashed UIDs, anti-replay, fail-secure doors, and a live WebSocket dashboard.
• The 5-layer architecture separates edge hardware from business logic via MQTT, making devices simple and swappable.

My Contributions

Built end-to-end as an academic master's project (single author):

• Designed the 5-layer pervasive-computing architecture and the MQTT topic contract (door/scan, door/command, door/status).
• Implemented the ESP32 firmware: UHF frame parsing, on-device SHA-256 hashing, nonce generation, broker auto-discovery, and actuator control. Migrated the reader from MFRC522 to HW-VX6330K UHF over RS485.
• Wrote the Go backend: MQTT handler, credential validation, rate limiting, anti-replay, WebSocket streaming, and the REST API.
• Built the Next.js dashboard (live access log, user management, manual door override) and the Docker Compose infrastructure.
• Documented the security model and wiring in bilingual READMEs.

References

[1] A. S. Shina, "rfid-access-control — Smart Door: My IoT RFID Access Control System," GitHub repository, 2026. [Online]. Available: https://github.com/ave-shina/rfid-access-control

[2] Eclipse Mosquitto, "Mosquitto — an open source MQTT broker," mosquitto.org, 2026. [Online]. Available: https://mosquitto.org

[3] Eclipse Foundation, "MQTT: the standard for IoT messaging," mqtt.org, 2026. [Online]. Available: https://mqtt.org

[4] Espressif, "ESP32 — a feature-rich MCU with integrated Wi-Fi and Bluetooth," espressif.com, 2026. [Online]. Available: https://www.espressif.com/en/products/socs/esp32