# vd-phuc-2k5/smartlock architecture

> Architecture diagram of the GitHub repository vd-phuc-2k5/smartlock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vd-phuc-2k5/smartlock
- Repository: https://github.com/vd-phuc-2k5/smartlock

## Overview

SmartLock combines ESP32 firmware, an MQTT/OTP/card backend, and a Next.js card-management client. The main access workflow is RFID scan → server verification → OTP delivery → keypad entry → door actuation; enrollment and camera streaming/capture are additional capabilities. The README documents MQTT and client behavior, while source excerpts show firmware dispatch, backend routes, and integration calls. Several unsampled modules are included as documented subsystems; their internal links are omitted where evidence is unavailable.

Main entry points: [`src/state/LockController.cpp`](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/state/LockController.cpp) (Lock controller), [`server/src/main.ts`](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/main.ts) (MQTT and HTTP entry), [`src/state`](https://github.com/vd-phuc-2k5/smartlock/tree/master/src/state) (Access states), [`server/src/otp/OtpService.ts`](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpService.ts) (OTP issuance and checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["ESP32 firmware"]
  node_keypad["Keypad input<br/>[KeypadService.cpp]"]
  node_rfid["RFID reader<br/>[RfidService.cpp]"]
  node_controller["Lock controller<br/>[LockController.cpp]"]
  node_states["Access states"]
  node_otp_firmware["OTP verification<br/>[OtpService.cpp]"]
  node_door["Door actuator<br/>[DoorLock.cpp]"]
  node_indicators["Access indicators"]
  node_lcd["LCD display<br/>[LcdService.cpp]"]
  node_mqtt_firmware["Firmware MQTT<br/>[MqttClient.cpp]"]
  node_configuration["Device configuration<br/>[ConfigManager.cpp]"]
  node_web_config["Wi-Fi setup"]
end

subgraph group_backend["Backend services"]
  node_server["MQTT and HTTP entry<br/>[main.ts]"]
  node_card_service["Card enrollment and checks<br/>[CardService.ts]"]
  node_card_store[("Card store<br/>[CardStore.ts]")]
  node_otp_service["OTP issuance and checks<br/>[OtpService.ts]"]
  node_otp_generator["OTP generator<br/>[OtpGenerator.ts]"]
  node_otp_store[("OTP store<br/>[OtpStore.ts]")]
  node_notifier["OTP notifications<br/>[OtpNotifier.ts]"]
  node_email_notifier["Email notifier<br/>[EmailNotifier.ts]"]
  node_smtp["SMTP mailer<br/>[SmtpMailer.ts]"]
end

subgraph group_client["Web client"]
  node_client_ui["Card management UI<br/>[CardManager.tsx]"]
  node_client_cards["Card API client<br/>[cards.ts]"]
end

subgraph group_camera["Camera features"]
  node_camera_firmware["Camera capture and stream<br/>[CameraService.cpp]"]
  node_camera_transport["Camera transport"]
  node_camera_api["Camera upload and state<br/>[main.ts]"]
  node_camera_view["Camera viewer<br/>[CameraViewer.tsx]"]
end

node_user(("User"))
node_broker(("MQTT broker"))
node_email_service(("Email service"))

node_user -->|"scans card"| node_rfid
node_rfid -->|"dispatches UID"| node_controller
node_user -->|"enters code"| node_keypad
node_keypad -.->|"dispatches keys"| node_controller
node_controller -->|"dispatches events"| node_states
node_controller -->|"requests OTP"| node_mqtt_firmware
node_controller -->|"updates display"| node_lcd
node_states -.->|"verifies entry"| node_otp_firmware
node_states -.->|"controls lock"| node_door
node_states -.->|"signals outcome"| node_indicators
node_mqtt_firmware -->|"publishes and subscribes"| node_broker
node_broker -->|"routes MQTT messages"| node_server
node_server -->|"handles card requests"| node_card_service
node_card_service -->|"reads and updates"| node_card_store
node_server -->|"issues and verifies"| node_otp_service
node_otp_service -->|"generates codes"| node_otp_generator
node_otp_service -->|"stores and checks"| node_otp_store
node_server -->|"notifies recipient"| node_notifier
node_notifier -.->|"dispatches email"| node_email_notifier
node_email_notifier -->|"sends mail"| node_smtp
node_smtp -.->|"delivers email"| node_email_service
node_user -->|"manages cards"| node_client_ui
node_client_ui -.->|"uses API client"| node_client_cards
node_client_cards -.->|"requests card API"| node_server
node_user -.->|"views camera"| node_camera_view
node_camera_firmware -->|"captures and sends frames"| node_camera_transport
node_camera_transport -->|"uploads frames"| node_camera_api
node_camera_api -.->|"serves stream and state"| node_camera_view

click node_keypad "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/keypad/KeypadService.cpp"
click node_rfid "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/rfid/RfidService.cpp"
click node_controller "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/state/LockController.cpp"
click node_states "https://github.com/vd-phuc-2k5/smartlock/tree/master/src/state"
click node_otp_firmware "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/otp/OtpService.cpp"
click node_door "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/door/DoorLock.cpp"
click node_indicators "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/indicator/AccessIndicator.cpp"
click node_lcd "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/lcd/LcdService.cpp"
click node_mqtt_firmware "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/mqtt/MqttClient.cpp"
click node_configuration "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/config/ConfigManager.cpp"
click node_web_config "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/web/WebConfigService.cpp"
click node_server "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/main.ts"
click node_card_service "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/card/CardService.ts"
click node_card_store "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/card/CardStore.ts"
click node_otp_service "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpService.ts"
click node_otp_generator "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpGenerator.ts"
click node_otp_store "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpStore.ts"
click node_notifier "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/notify/OtpNotifier.ts"
click node_email_notifier "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/notify/EmailNotifier.ts"
click node_smtp "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/mail/SmtpMailer.ts"
click node_client_ui "https://github.com/vd-phuc-2k5/smartlock/blob/master/client/components/CardManager.tsx"
click node_client_cards "https://github.com/vd-phuc-2k5/smartlock/blob/master/client/lib/cards.ts"
click node_camera_firmware "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/camera/CameraService.cpp"
click node_camera_transport "https://github.com/vd-phuc-2k5/smartlock/blob/master/src/serial/SerialCameraTransport.cpp"
click node_camera_api "https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/main.ts"
click node_camera_view "https://github.com/vd-phuc-2k5/smartlock/blob/master/client/components/CameraViewer.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_keypad,node_rfid,node_controller,node_states,node_otp_firmware,node_door,node_indicators,node_lcd,node_mqtt_firmware,node_configuration,node_web_config,node_user toneBlue
class node_server,node_card_service,node_card_store,node_otp_service,node_otp_generator,node_otp_store,node_notifier,node_email_notifier,node_smtp toneAmber
class node_client_ui,node_client_cards toneMint
class node_camera_firmware,node_camera_transport,node_camera_api,node_camera_view toneRose
class node_broker,node_email_service toneIndigo
```

## Components

### ESP32 firmware

- [Keypad input](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/keypad/KeypadService.cpp): `src/keypad/KeypadService.cpp`
- [RFID reader](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/rfid/RfidService.cpp): `src/rfid/RfidService.cpp`
- [Lock controller](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/state/LockController.cpp): `src/state/LockController.cpp`
- [Access states](https://github.com/vd-phuc-2k5/smartlock/tree/master/src/state): `src/state`
- [OTP verification](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/otp/OtpService.cpp): `src/otp/OtpService.cpp`
- [Door actuator](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/door/DoorLock.cpp): `src/door/DoorLock.cpp`
- [Access indicators](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/indicator/AccessIndicator.cpp): `src/indicator/AccessIndicator.cpp`
- [LCD display](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/lcd/LcdService.cpp): `src/lcd/LcdService.cpp`
- [Firmware MQTT](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/mqtt/MqttClient.cpp): `src/mqtt/MqttClient.cpp`
- [Device configuration](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/config/ConfigManager.cpp): `src/config/ConfigManager.cpp`
- [Wi-Fi setup](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/web/WebConfigService.cpp): `src/web/WebConfigService.cpp`

### Backend services

- [MQTT and HTTP entry](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/main.ts): `server/src/main.ts`
- [Card enrollment and checks](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/card/CardService.ts): `server/src/card/CardService.ts`
- [Card store](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/card/CardStore.ts): `server/src/card/CardStore.ts`
- [OTP issuance and checks](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpService.ts): `server/src/otp/OtpService.ts`
- [OTP generator](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpGenerator.ts): `server/src/otp/OtpGenerator.ts`
- [OTP store](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/otp/OtpStore.ts): `server/src/otp/OtpStore.ts`
- [OTP notifications](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/notify/OtpNotifier.ts): `server/src/notify/OtpNotifier.ts`
- [Email notifier](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/notify/EmailNotifier.ts): `server/src/notify/EmailNotifier.ts`
- [SMTP mailer](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/mail/SmtpMailer.ts): `server/src/mail/SmtpMailer.ts`

### Web client

- [Card management UI](https://github.com/vd-phuc-2k5/smartlock/blob/master/client/components/CardManager.tsx): `client/components/CardManager.tsx`
- [Card API client](https://github.com/vd-phuc-2k5/smartlock/blob/master/client/lib/cards.ts): `client/lib/cards.ts`

### Camera features

- [Camera capture and stream](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/camera/CameraService.cpp): `src/camera/CameraService.cpp`
- [Camera transport](https://github.com/vd-phuc-2k5/smartlock/blob/master/src/serial/SerialCameraTransport.cpp): `src/serial/SerialCameraTransport.cpp`
- [Camera upload and state](https://github.com/vd-phuc-2k5/smartlock/blob/master/server/src/main.ts): `server/src/main.ts`
- [Camera viewer](https://github.com/vd-phuc-2k5/smartlock/blob/master/client/components/CameraViewer.tsx): `client/components/CameraViewer.tsx`

### Other components

- **User**
- **MQTT broker**
- **Email service**

## Connections

- User → RFID reader: scans card
- RFID reader → Lock controller: dispatches UID
- User → Keypad input: enters code
- Keypad input → Lock controller: dispatches keys
- Lock controller → Access states: dispatches events (evidence: `src/state/LockController.cpp`)
- Lock controller → Firmware MQTT: requests OTP (evidence: `src/state/LockController.cpp`)
- Lock controller → LCD display: updates display
- Access states → OTP verification: verifies entry
- Access states → Door actuator: controls lock
- Access states → Access indicators: signals outcome
- Firmware MQTT → MQTT broker: publishes and subscribes
- MQTT broker → MQTT and HTTP entry: routes MQTT messages
- MQTT and HTTP entry → Card enrollment and checks: handles card requests (evidence: `server/src/main.ts`)
- Card enrollment and checks → Card store: reads and updates (evidence: `server/src/card/CardService.ts`)
- MQTT and HTTP entry → OTP issuance and checks: issues and verifies (evidence: `server/src/main.ts`)
- OTP issuance and checks → OTP generator: generates codes (evidence: `server/src/otp/OtpService.ts`)
- OTP issuance and checks → OTP store: stores and checks (evidence: `server/src/otp/OtpService.ts`)
- MQTT and HTTP entry → OTP notifications: notifies recipient (evidence: `server/src/main.ts`)
- OTP notifications → Email notifier: dispatches email (evidence: `server/src/notify/EmailNotifier.ts`)
- Email notifier → SMTP mailer: sends mail (evidence: `server/src/notify/EmailNotifier.ts`)
- SMTP mailer → Email service: delivers email
- User → Card management UI: manages cards
- Card management UI → Card API client: uses API client
- Card API client → MQTT and HTTP entry: requests card API
- User → Camera viewer: views camera
- Camera capture and stream → Camera transport: captures and sends frames
- Camera transport → Camera upload and state: uploads frames
- Camera upload and state → Camera viewer: serves stream and state
