# espressif/esp-idf architecture

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

- Interactive diagram: https://gitdiagram.com/espressif/esp-idf
- Repository: https://github.com/espressif/esp-idf

## Overview

ESP-IDF is an embedded development framework for Espressif SoCs. An application uses framework APIs to perform device functions and persist state; OTA operations and boot-time image/security handling are distinct lifecycle capabilities. The sampled code confirms TEE secure storage uses NVS, while the tree identifies Bluetooth bonding storage, app tracing, and hardware SHA support. Their broader call wiring is not established by the excerpts, so those subsystems are shown without speculative connections.

Main entry points: [`components/app_trace/app_trace.c`](https://github.com/espressif/esp-idf/blob/master/components/app_trace/app_trace.c) (Application tracing), [`components/bootloader/subproject/main/bootloader_start.c`](https://github.com/espressif/esp-idf/blob/master/components/bootloader/subproject/main/bootloader_start.c) (Bootloader startup), [`components/app_update/esp_ota_ops.c`](https://github.com/espressif/esp-idf/blob/master/components/app_update/esp_ota_ops.c) (OTA operations), [`components/bootloader_support/src/bootloader_utility.c`](https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/src/bootloader_utility.c) (Boot utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Device lifecycle"]
  node_ota["OTA operations<br/>[esp_ota_ops.c]"]
  node_autoconfirm["OTA auto-confirm<br/>[ota_auto_confirm.c]"]
  node_boot["Bootloader startup<br/>[bootloader_start.c]"]
  node_bootutil["Boot utilities"]
  node_secureboot["Secure boot<br/>[secure_boot.c]"]
  node_flash["Flash access<br/>[bootloader_flash.c]"]
end

subgraph group_storage["Persistence and security"]
  node_nvs[("NVS storage<br/>[nvs_storage.cpp]")]
  node_teestorage["TEE secure storage<br/>[tee_sec_storage.c]"]
end

subgraph group_connectivity["Bluetooth"]
  node_blestorage["BLE bond storage<br/>[btc_ble_storage.c]"]
  node_btstorage["Bluetooth storage<br/>[btc_storage.c]"]
end

subgraph group_diagnostics["Diagnostics and crypto"]
  node_apptrace["Application tracing<br/>[app_trace.c]"]
  node_traceuart["UART trace port<br/>[port_uart.c]"]
  node_tracejtag["JTAG trace port<br/>[port_jtag.c]"]
  node_sha["Hardware SHA API"]
end

subgraph group_runtime["Application runtime"]
  node_pthreadtls["Thread-local storage"]
end

node_app(("Device application"))
node_soc(("Espressif SoC"))
node_peer(("Bluetooth peer"))

node_app -->|"requests update"| node_ota
node_app -->|"uses secure keys"| node_teestorage
node_teestorage -->|"reads/writes"| node_nvs
node_app -->|"uses bonding"| node_blestorage
node_app -->|"uses bond records"| node_btstorage
node_peer -->|"bond information"| node_blestorage
node_app -->|"emits trace"| node_apptrace
node_apptrace -.->|"routes trace"| node_traceuart
node_apptrace -.->|"routes trace"| node_tracejtag
node_app -->|"hashes data"| node_sha
node_app -->|"uses thread state"| node_pthreadtls
node_soc -->|"provides engine"| node_sha
node_soc -->|"provides flash"| node_flash
node_boot -->|"uses boot utilities"| node_bootutil
node_boot -.->|"checks image"| node_secureboot
node_bootutil -->|"accesses flash"| node_flash
node_ota -.->|"confirmation support"| node_autoconfirm

click node_ota "https://github.com/espressif/esp-idf/blob/master/components/app_update/esp_ota_ops.c"
click node_autoconfirm "https://github.com/espressif/esp-idf/blob/master/components/app_update/ota_auto_confirm.c"
click node_boot "https://github.com/espressif/esp-idf/blob/master/components/bootloader/subproject/main/bootloader_start.c"
click node_bootutil "https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/src/bootloader_utility.c"
click node_secureboot "https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/src/secure_boot.c"
click node_flash "https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/bootloader_flash/src/bootloader_flash.c"
click node_nvs "https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/src/nvs_storage.cpp"
click node_teestorage "https://github.com/espressif/esp-idf/blob/master/components/esp_tee/subproject/components/tee_sec_storage/tee_sec_storage.c"
click node_blestorage "https://github.com/espressif/esp-idf/blob/master/components/bt/host/bluedroid/btc/core/btc_ble_storage.c"
click node_btstorage "https://github.com/espressif/esp-idf/blob/master/components/bt/host/bluedroid/btc/core/btc_storage.c"
click node_apptrace "https://github.com/espressif/esp-idf/blob/master/components/app_trace/app_trace.c"
click node_traceuart "https://github.com/espressif/esp-idf/blob/master/components/app_trace/port/port_uart.c"
click node_tracejtag "https://github.com/espressif/esp-idf/blob/master/components/app_trace/port/xtensa/port_jtag.c"
click node_sha "https://github.com/espressif/esp-idf/blob/master/components/mbedtls/port/include/sha/sha_parallel_engine.h"
click node_pthreadtls "https://github.com/espressif/esp-idf/blob/master/components/pthread/pthread_local_storage.c"

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_ota,node_autoconfirm,node_boot,node_bootutil,node_secureboot,node_flash toneBlue
class node_nvs,node_teestorage toneAmber
class node_blestorage,node_btstorage toneMint
class node_apptrace,node_traceuart,node_tracejtag,node_sha toneRose
class node_pthreadtls,node_app,node_soc,node_peer toneIndigo
```

## Components

### Device lifecycle

- [OTA operations](https://github.com/espressif/esp-idf/blob/master/components/app_update/esp_ota_ops.c): `components/app_update/esp_ota_ops.c`
- [OTA auto-confirm](https://github.com/espressif/esp-idf/blob/master/components/app_update/ota_auto_confirm.c): `components/app_update/ota_auto_confirm.c`
- [Bootloader startup](https://github.com/espressif/esp-idf/blob/master/components/bootloader/subproject/main/bootloader_start.c): `components/bootloader/subproject/main/bootloader_start.c`
- [Boot utilities](https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/src/bootloader_utility.c): `components/bootloader_support/src/bootloader_utility.c`
- [Secure boot](https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/src/secure_boot.c): `components/bootloader_support/src/secure_boot.c`
- [Flash access](https://github.com/espressif/esp-idf/blob/master/components/bootloader_support/bootloader_flash/src/bootloader_flash.c): `components/bootloader_support/bootloader_flash/src/bootloader_flash.c`

### Persistence and security

- [NVS storage](https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/src/nvs_storage.cpp): `components/nvs_flash/src/nvs_storage.cpp`
- [TEE secure storage](https://github.com/espressif/esp-idf/blob/master/components/esp_tee/subproject/components/tee_sec_storage/tee_sec_storage.c): `components/esp_tee/subproject/components/tee_sec_storage/tee_sec_storage.c`

### Bluetooth

- [BLE bond storage](https://github.com/espressif/esp-idf/blob/master/components/bt/host/bluedroid/btc/core/btc_ble_storage.c): `components/bt/host/bluedroid/btc/core/btc_ble_storage.c`
- [Bluetooth storage](https://github.com/espressif/esp-idf/blob/master/components/bt/host/bluedroid/btc/core/btc_storage.c): `components/bt/host/bluedroid/btc/core/btc_storage.c`

### Diagnostics and crypto

- [Application tracing](https://github.com/espressif/esp-idf/blob/master/components/app_trace/app_trace.c): `components/app_trace/app_trace.c`
- [UART trace port](https://github.com/espressif/esp-idf/blob/master/components/app_trace/port/port_uart.c): `components/app_trace/port/port_uart.c`
- [JTAG trace port](https://github.com/espressif/esp-idf/blob/master/components/app_trace/port/xtensa/port_jtag.c): `components/app_trace/port/xtensa/port_jtag.c`
- [Hardware SHA API](https://github.com/espressif/esp-idf/blob/master/components/mbedtls/port/include/sha/sha_parallel_engine.h): `components/mbedtls/port/include/sha/sha_parallel_engine.h`

### Application runtime

- [Thread-local storage](https://github.com/espressif/esp-idf/blob/master/components/pthread/pthread_local_storage.c): `components/pthread/pthread_local_storage.c`

### Other components

- **Device application**
- **Espressif SoC**
- **Bluetooth peer**

## Connections

- Device application → OTA operations: requests update
- Device application → TEE secure storage: uses secure keys
- TEE secure storage → NVS storage: reads/writes
- Device application → BLE bond storage: uses bonding
- Device application → Bluetooth storage: uses bond records
- Bluetooth peer → BLE bond storage: bond information
- Device application → Application tracing: emits trace
- Application tracing → UART trace port: routes trace
- Application tracing → JTAG trace port: routes trace
- Device application → Hardware SHA API: hashes data
- Device application → Thread-local storage: uses thread state
- Espressif SoC → Hardware SHA API: provides engine
- Espressif SoC → Flash access: provides flash
- Bootloader startup → Boot utilities: uses boot utilities
- Bootloader startup → Secure boot: checks image
- Boot utilities → Flash access: accesses flash
- OTA operations → OTA auto-confirm: confirmation support