# fufu4826/smartlock-esp32 architecture

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

- Interactive diagram: https://gitdiagram.com/fufu4826/smartlock-esp32
- Repository: https://github.com/fufu4826/smartlock-esp32

## Overview

ESP32-035 SmartLock is a locally hosted door-lock firmware: an Owner sets it up in a phone browser, registered phones request timed access, and the Owner manages identities and settings over the device’s AP or home LAN. A physical touchscreen Admin flow provides emergency unlock and factory reset. The graph also includes network recovery, LINE broadcast, and the main persistence/security layers. README documents several capabilities whose implementation was not sampled; those are mapped to their documented source areas, with uncertain wiring omitted.

Main entry points: [`src/network/WebServerManager.cpp`](https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/WebServerManager.cpp) (HTTP API), [`src/storage/IdentityStore.cpp`](https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/IdentityStore.cpp) (Identity and auth), [`src/app/FirstOwnerSetup.cpp`](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/FirstOwnerSetup.cpp) (First-owner setup), [`src/app/AccessController.cpp`](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/AccessController.cpp) (Access control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Lock workflows"]
  node_setup["First-owner setup"]
  node_access["Access control"]
  node_enrollment["Enrollment management"]
  node_state["App state machine"]
  node_physical["Physical admin<br/>[PhysicalAdmin.cpp]"]
  node_reset["Factory reset"]
end

subgraph group_webnet["Web and network"]
  node_web["Phone pages<br/>[WebAssets.h]"]
  node_http["HTTP API"]
  node_network["Wi-Fi and recovery<br/>[NetworkManager.cpp]"]
  node_origin["Canonical origin"]
end

subgraph group_security["Identity and security"]
  node_sessions["QR sessions<br/>[SessionManager.cpp]"]
  node_pin["Admin PIN policy<br/>[AdminPin.cpp]"]
end

subgraph group_hardware["Device hardware"]
  node_lock["Lock output<br/>[LockController.cpp]"]
  node_display["Display and QR<br/>[DisplayManager.cpp]"]
  node_touchmgr["Touch manager<br/>[TouchManager.cpp]"]
end

subgraph group_services["Storage and services"]
  node_identity[("Identity and auth<br/>[IdentityStore.cpp]")]
  node_config[("Device configuration<br/>[ConfigStore.cpp]")]
  node_storage[("SD health and files<br/>[StorageHealth.cpp]")]
  node_line["LINE broadcast"]
  node_time["Time synchronization<br/>[TimeManager.cpp]"]
end

node_owner(("Owner"))
node_phone(("Registered phone"))
node_touch(("Touch input"))
node_lineapi(("LINE Official Account"))

node_owner -->|"uses setup/manage"| node_web
node_phone -->|"scans QR"| node_web
node_web -->|"sends requests"| node_http
node_http -->|"dispatches setup"| node_setup
node_http -->|"dispatches access"| node_access
node_http -->|"dispatches management"| node_enrollment
node_http -->|"reads network state"| node_network
node_http -->|"serves LINE controls"| node_line
node_setup -->|"validates setup session"| node_sessions
node_setup -->|"creates owner identity"| node_identity
node_setup -->|"saves setup state"| node_config
node_access -->|"checks credentials"| node_identity
node_access -->|"reads unlock duration"| node_config
node_access -->|"requests timed unlock"| node_lock
node_enrollment -->|"validates enrollment"| node_sessions
node_enrollment -->|"reads and updates identities"| node_identity
node_enrollment -->|"builds enrollment URL"| node_origin
node_touch -->|"provides input"| node_touchmgr
node_touchmgr -->|"routes touch events"| node_state
node_state -->|"renders state"| node_display
node_display -->|"renders QR payload"| node_sessions
node_touchmgr -->|"routes admin touch"| node_physical
node_physical -->|"checks PIN"| node_pin
node_physical -->|"requests emergency unlock"| node_lock
node_physical -->|"dispatches reset"| node_reset
node_reset -->|"clears identity data"| node_identity
node_reset -->|"clears setup configuration"| node_config
node_reset -->|"resets SD records"| node_storage
node_storage -->|"validates store"| node_identity
node_network -->|"sets device hostname"| node_origin
node_line -.->|"broadcasts over TLS"| node_lineapi
node_time -.->|"provides time context"| node_line

click node_web "https://github.com/fufu4826/smartlock-esp32/blob/main/src/web/WebAssets.h"
click node_http "https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/WebServerManager.cpp"
click node_network "https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/NetworkManager.cpp"
click node_origin "https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/CanonicalOrigin.cpp"
click node_setup "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/FirstOwnerSetup.cpp"
click node_access "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/AccessController.cpp"
click node_enrollment "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/EnrollmentManager.cpp"
click node_state "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/AppStateMachine.cpp"
click node_physical "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/PhysicalAdmin.cpp"
click node_reset "https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/FactoryResetController.cpp"
click node_sessions "https://github.com/fufu4826/smartlock-esp32/blob/main/src/qr/SessionManager.cpp"
click node_pin "https://github.com/fufu4826/smartlock-esp32/blob/main/src/security/AdminPin.cpp"
click node_identity "https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/IdentityStore.cpp"
click node_config "https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/ConfigStore.cpp"
click node_storage "https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/StorageHealth.cpp"
click node_lock "https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/LockController.cpp"
click node_display "https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/DisplayManager.cpp"
click node_touchmgr "https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/TouchManager.cpp"
click node_line "https://github.com/fufu4826/smartlock-esp32/blob/main/src/notifications/LineNotifications.cpp"
click node_time "https://github.com/fufu4826/smartlock-esp32/blob/main/src/events/TimeManager.cpp"

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_setup,node_access,node_enrollment,node_state,node_physical,node_reset toneBlue
class node_web,node_http,node_network,node_origin toneAmber
class node_sessions,node_pin toneMint
class node_lock,node_display,node_touchmgr toneRose
class node_identity,node_config,node_storage,node_line,node_time,node_owner,node_phone,node_touch,node_lineapi toneIndigo
```

## Components

### Lock workflows

- [First-owner setup](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/FirstOwnerSetup.cpp): `src/app/FirstOwnerSetup.cpp`
- [Access control](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/AccessController.cpp): `src/app/AccessController.cpp`
- [Enrollment management](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/EnrollmentManager.cpp): `src/app/EnrollmentManager.cpp`
- [App state machine](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/AppStateMachine.cpp): `src/app/AppStateMachine.cpp`
- [Physical admin](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/PhysicalAdmin.cpp): `src/app/PhysicalAdmin.cpp`
- [Factory reset](https://github.com/fufu4826/smartlock-esp32/blob/main/src/app/FactoryResetController.cpp): `src/app/FactoryResetController.cpp`

### Web and network

- [Phone pages](https://github.com/fufu4826/smartlock-esp32/blob/main/src/web/WebAssets.h): `src/web/WebAssets.h`
- [HTTP API](https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/WebServerManager.cpp): `src/network/WebServerManager.cpp`
- [Wi-Fi and recovery](https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/NetworkManager.cpp): `src/network/NetworkManager.cpp`
- [Canonical origin](https://github.com/fufu4826/smartlock-esp32/blob/main/src/network/CanonicalOrigin.cpp): `src/network/CanonicalOrigin.cpp`

### Identity and security

- [QR sessions](https://github.com/fufu4826/smartlock-esp32/blob/main/src/qr/SessionManager.cpp): `src/qr/SessionManager.cpp`
- [Admin PIN policy](https://github.com/fufu4826/smartlock-esp32/blob/main/src/security/AdminPin.cpp): `src/security/AdminPin.cpp`

### Device hardware

- [Lock output](https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/LockController.cpp): `src/hardware/LockController.cpp`
- [Display and QR](https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/DisplayManager.cpp): `src/hardware/DisplayManager.cpp`
- [Touch manager](https://github.com/fufu4826/smartlock-esp32/blob/main/src/hardware/TouchManager.cpp): `src/hardware/TouchManager.cpp`

### Storage and services

- [Identity and auth](https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/IdentityStore.cpp): `src/storage/IdentityStore.cpp`
- [Device configuration](https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/ConfigStore.cpp): `src/storage/ConfigStore.cpp`
- [SD health and files](https://github.com/fufu4826/smartlock-esp32/blob/main/src/storage/StorageHealth.cpp): `src/storage/StorageHealth.cpp`
- [LINE broadcast](https://github.com/fufu4826/smartlock-esp32/blob/main/src/notifications/LineNotifications.cpp): `src/notifications/LineNotifications.cpp`
- [Time synchronization](https://github.com/fufu4826/smartlock-esp32/blob/main/src/events/TimeManager.cpp): `src/events/TimeManager.cpp`

### Other components

- **Owner**
- **Registered phone**
- **Touch input**
- **LINE Official Account**

## Connections

- Owner → Phone pages: uses setup/manage
- Registered phone → Phone pages: scans QR
- Phone pages → HTTP API: sends requests
- HTTP API → First-owner setup: dispatches setup
- HTTP API → Access control: dispatches access
- HTTP API → Enrollment management: dispatches management
- HTTP API → Wi-Fi and recovery: reads network state
- HTTP API → LINE broadcast: serves LINE controls
- First-owner setup → QR sessions: validates setup session
- First-owner setup → Identity and auth: creates owner identity
- First-owner setup → Device configuration: saves setup state
- Access control → Identity and auth: checks credentials
- Access control → Device configuration: reads unlock duration
- Access control → Lock output: requests timed unlock
- Enrollment management → QR sessions: validates enrollment
- Enrollment management → Identity and auth: reads and updates identities
- Enrollment management → Canonical origin: builds enrollment URL
- Touch input → Touch manager: provides input
- Touch manager → App state machine: routes touch events
- App state machine → Display and QR: renders state
- Display and QR → QR sessions: renders QR payload
- Touch manager → Physical admin: routes admin touch
- Physical admin → Admin PIN policy: checks PIN
- Physical admin → Lock output: requests emergency unlock
- Physical admin → Factory reset: dispatches reset
- Factory reset → Identity and auth: clears identity data
- Factory reset → Device configuration: clears setup configuration
- Factory reset → SD health and files: resets SD records
- SD health and files → Identity and auth: validates store
- Wi-Fi and recovery → Canonical origin: sets device hostname
- LINE broadcast → LINE Official Account: broadcasts over TLS
- Time synchronization → LINE broadcast: provides time context