# roquerodrigo/ha-ttlock-ble architecture

> Architecture diagram of the GitHub repository roquerodrigo/ha-ttlock-ble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roquerodrigo/ha-ttlock-ble
- Repository: https://github.com/roquerodrigo/ha-ttlock-ble

## Overview

This Home Assistant integration configures TTLock locks, obtains cloud-backed or manually entered keys, then exposes local BLE control and lock state as Home Assistant entities. Its runtime combines passive advertisement tracking with on-demand BLE sessions; sessions also read operation logs, credentials, and clock/settings data. The README documents discovery, 2FA, reauthentication, and diagnostics, while sampled source confirms setup, advertisement tracking, connection handling, and log-event dispatch. Some platform and configuration-flow links are documented rather than verified in sampled implementation.

Main entry points: [`custom_components/ttlock_ble/coordinator.py`](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/coordinator.py) (Runtime coordinator), [`custom_components/ttlock_ble/__init__.py`](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/__init__.py) (Entry setup), [`custom_components/ttlock_ble/connection.py`](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/connection.py) (BLE connection), [`custom_components/ttlock_ble/config_flow.py`](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/config_flow.py) (Config and reauth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and keys"]
  node_config_flow["Config and reauth<br/>[config_flow.py]"]
  node_options_flow["Options flow<br/>[options_flow.py]"]
  node_api["Cloud API client<br/>[api.py]"]
  node_manual_key["Manual key entry<br/>[manual_key.py]"]
  node_setup_runtime["Entry setup<br/>[__init__.py]"]
  node_key_privileges["Key privileges<br/>[key_privileges.py]"]
end

subgraph group_ble["BLE runtime"]
  node_advertisement["Advertisement tracker<br/>[advertisement.py]"]
  node_coordinator["Runtime coordinator<br/>[coordinator.py]"]
  node_connection["BLE connection<br/>[connection.py]"]
end

subgraph group_state["State and records"]
  node_passcode_ledger["Credential naming<br/>[passcode_ledger.py]"]
  node_lock_state["Lock state model<br/>[lock_state.py]"]
end

subgraph group_entities["Home Assistant entities"]
  node_lock_platform["Lock controls<br/>[lock.py]"]
  node_entity_base["Entity base<br/>[entity.py]"]
  node_sensor["Sensors<br/>[sensor.py]"]
  node_binary_sensor["Binary sensors<br/>[binary_sensor.py]"]
  node_event_entity["Operation events<br/>[event.py]"]
  node_other_entities["Other platforms<br/>[button.py]"]
end

subgraph group_support["Diagnostics and persistence"]
  node_clock_store[("Clock sync store")]
  node_description_store[("Device description store")]
  node_diagnostics["Diagnostics export<br/>[diagnostics.py]"]
  node_const["Integration constants<br/>[const.py]"]
end

node_user(("Home Assistant user"))
node_ha(("Home Assistant"))
node_cloud["TTLock cloud"]
node_lock_device["TTLock lock"]

node_user -->|"configures"| node_config_flow
node_config_flow -.->|"authenticates"| node_api
node_api -->|"downloads keys"| node_cloud
node_config_flow -.->|"accepts key"| node_manual_key
node_user -->|"edits options"| node_options_flow
node_ha -->|"sets up entry"| node_setup_runtime
node_setup_runtime -->|"registers tracking"| node_advertisement
node_setup_runtime -->|"creates coordinator"| node_coordinator
node_setup_runtime -->|"creates connections"| node_connection
node_setup_runtime -->|"forwards platforms"| node_other_entities
node_advertisement -->|"publishes state"| node_coordinator
node_lock_device -->|"broadcasts state"| node_advertisement
node_coordinator -->|"fetches log"| node_connection
node_connection -->|"communicates BLE"| node_lock_device
node_lock_platform -->|"commands lock"| node_connection
node_coordinator -->|"publishes snapshot"| node_lock_state
node_coordinator -.->|"persists clock sync"| node_clock_store
node_coordinator -.->|"persists description"| node_description_store
node_coordinator -->|"dispatches log records"| node_event_entity
node_event_entity -.->|"resolves credentials"| node_passcode_ledger
node_coordinator -->|"supplies state"| node_sensor
node_coordinator -->|"supplies state"| node_binary_sensor
node_entity_base -->|"reads snapshot"| node_coordinator
node_ha -->|"requests dump"| node_diagnostics
node_setup_runtime -->|"uses privileges"| node_key_privileges

click node_config_flow "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/config_flow.py"
click node_options_flow "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/options_flow.py"
click node_api "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/api.py"
click node_manual_key "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/manual_key.py"
click node_setup_runtime "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/__init__.py"
click node_key_privileges "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/key_privileges.py"
click node_advertisement "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/advertisement.py"
click node_coordinator "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/coordinator.py"
click node_connection "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/connection.py"
click node_lock_platform "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/lock.py"
click node_entity_base "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/entity.py"
click node_sensor "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/sensor.py"
click node_binary_sensor "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/binary_sensor.py"
click node_event_entity "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/event.py"
click node_other_entities "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/button.py"
click node_passcode_ledger "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/passcode_ledger.py"
click node_lock_state "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/data/lock_state.py"
click node_clock_store "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/clock_sync_store.py"
click node_description_store "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/device_description_store.py"
click node_diagnostics "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/diagnostics.py"
click node_const "https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/const.py"

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_config_flow,node_options_flow,node_api,node_manual_key,node_setup_runtime,node_key_privileges,node_user toneBlue
class node_advertisement,node_coordinator,node_connection toneAmber
class node_passcode_ledger,node_lock_state toneMint
class node_lock_platform,node_entity_base,node_sensor,node_binary_sensor,node_event_entity,node_other_entities toneRose
class node_clock_store,node_description_store,node_diagnostics,node_const,node_ha,node_cloud,node_lock_device toneIndigo
```

## Components

### Setup and keys

- [Config and reauth](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/config_flow.py): `custom_components/ttlock_ble/config_flow.py`
- [Options flow](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/options_flow.py): `custom_components/ttlock_ble/options_flow.py`
- [Cloud API client](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/api.py): `custom_components/ttlock_ble/api.py`
- [Manual key entry](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/manual_key.py): `custom_components/ttlock_ble/manual_key.py`
- [Entry setup](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/__init__.py): `custom_components/ttlock_ble/__init__.py`
- [Key privileges](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/key_privileges.py): `custom_components/ttlock_ble/key_privileges.py`

### BLE runtime

- [Advertisement tracker](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/advertisement.py): `custom_components/ttlock_ble/advertisement.py`
- [Runtime coordinator](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/coordinator.py): `custom_components/ttlock_ble/coordinator.py`
- [BLE connection](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/connection.py): `custom_components/ttlock_ble/connection.py`

### State and records

- [Credential naming](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/passcode_ledger.py): `custom_components/ttlock_ble/passcode_ledger.py`
- [Lock state model](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/data/lock_state.py): `custom_components/ttlock_ble/data/lock_state.py`

### Home Assistant entities

- [Lock controls](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/lock.py): `custom_components/ttlock_ble/lock.py`
- [Entity base](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/entity.py): `custom_components/ttlock_ble/entity.py`
- [Sensors](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/sensor.py): `custom_components/ttlock_ble/sensor.py`
- [Binary sensors](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/binary_sensor.py): `custom_components/ttlock_ble/binary_sensor.py`
- [Operation events](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/event.py): `custom_components/ttlock_ble/event.py`
- [Other platforms](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/button.py): `custom_components/ttlock_ble/button.py`

### Diagnostics and persistence

- [Clock sync store](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/clock_sync_store.py): `custom_components/ttlock_ble/clock_sync_store.py`
- [Device description store](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/device_description_store.py): `custom_components/ttlock_ble/device_description_store.py`
- [Diagnostics export](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/diagnostics.py): `custom_components/ttlock_ble/diagnostics.py`
- [Integration constants](https://github.com/roquerodrigo/ha-ttlock-ble/blob/main/custom_components/ttlock_ble/const.py): `custom_components/ttlock_ble/const.py`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **TTLock cloud**
- **TTLock lock**

## Connections

- Home Assistant user → Config and reauth: configures
- Config and reauth → Cloud API client: authenticates
- Cloud API client → TTLock cloud: downloads keys
- Config and reauth → Manual key entry: accepts key
- Home Assistant user → Options flow: edits options
- Home Assistant → Entry setup: sets up entry (evidence: `custom_components/ttlock_ble/__init__.py`)
- Entry setup → Advertisement tracker: registers tracking (evidence: `custom_components/ttlock_ble/__init__.py`)
- Entry setup → Runtime coordinator: creates coordinator (evidence: `custom_components/ttlock_ble/__init__.py`)
- Entry setup → BLE connection: creates connections (evidence: `custom_components/ttlock_ble/__init__.py`)
- Entry setup → Other platforms: forwards platforms (evidence: `custom_components/ttlock_ble/__init__.py`)
- Advertisement tracker → Runtime coordinator: publishes state (evidence: `custom_components/ttlock_ble/advertisement.py`)
- TTLock lock → Advertisement tracker: broadcasts state
- Runtime coordinator → BLE connection: fetches log (evidence: `custom_components/ttlock_ble/coordinator.py`)
- BLE connection → TTLock lock: communicates BLE
- Lock controls → BLE connection: commands lock (evidence: `custom_components/ttlock_ble/lock.py`)
- Runtime coordinator → Lock state model: publishes snapshot (evidence: `custom_components/ttlock_ble/coordinator.py`)
- Runtime coordinator → Clock sync store: persists clock sync (evidence: `custom_components/ttlock_ble/coordinator.py`)
- Runtime coordinator → Device description store: persists description (evidence: `custom_components/ttlock_ble/coordinator.py`)
- Runtime coordinator → Operation events: dispatches log records (evidence: `custom_components/ttlock_ble/event.py`)
- Operation events → Credential naming: resolves credentials
- Runtime coordinator → Sensors: supplies state (evidence: `custom_components/ttlock_ble/sensor.py`)
- Runtime coordinator → Binary sensors: supplies state (evidence: `custom_components/ttlock_ble/binary_sensor.py`)
- Entity base → Runtime coordinator: reads snapshot (evidence: `custom_components/ttlock_ble/entity.py`)
- Home Assistant → Diagnostics export: requests dump
- Entry setup → Key privileges: uses privileges (evidence: `custom_components/ttlock_ble/__init__.py`)