# folotoy/ai-passport architecture

> Architecture diagram of the GitHub repository folotoy/ai-passport, 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/folotoy/ai-passport
- Repository: https://github.com/folotoy/ai-passport

## Overview

FoloToy AI Passport is an open ESP32-C3 wearable platform; the checked-in `main` application is a hardware-test baseline, not a finished user application. Its main workflow initializes board services, presents a test menu, dispatches button input to a selected demo, and displays results on the device. The repository also provides reusable BSP support for display, controls, audio, battery, and shared I²C, plus Wi-Fi, BLE, radio, and low-power demonstrations. The graph follows the README and sampled source; some demo internals and startup wiring are not shown in the excerpts.

Main entry points: [`main/demo_low_power.c`](https://github.com/folotoy/ai-passport/blob/main/main/demo_low_power.c) (Low Power Demo), [`components/bsp/src/bsp_i2c.c`](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_i2c.c) (Shared I²C), [`components/bsp/src/bsp_display.c`](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_display.c) (Display BSP), [`components/bsp/src/bsp_button.c`](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_button.c) (Button BSP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Demo Application"]
  node_entry["Firmware Entry<br/>[main.c]"]
  node_input["Input Dispatch<br/>[main.c]"]
  node_navigation["Menu Navigation<br/>[demo_navigation.c]"]
  node_pixelui["Pixel UI<br/>[ui_pixel.c]"]
end

subgraph group_demos["Hardware Demos"]
  node_displaydemo["Display Demo<br/>[demo_display.c]"]
  node_buttondemo["Button Demo<br/>[demo_button.c]"]
  node_audiodemo["Audio Demo<br/>[demo_audio.c]"]
  node_batterydemo["Battery Demo<br/>[demo_battery.c]"]
  node_wifidemo["Wi-Fi Demo<br/>[demo_wifi.c]"]
  node_bledemo["BLE Demo<br/>[demo_ble.c]"]
  node_radiodemo["Radio Demo<br/>[demo_radio.c]"]
  node_sleepdemo["Low Power Demo<br/>[demo_low_power.c]"]
end

subgraph group_bsp["Board Support"]
  node_displaybsp["Display BSP<br/>[bsp_display.c]"]
  node_buttonbsp["Button BSP<br/>[bsp_button.c]"]
  node_audiobsp["Audio BSP<br/>[bsp_audio.c]"]
  node_batterybsp["Battery BSP<br/>[bsp_battery.c]"]
  node_i2cbsp["Shared I²C<br/>[bsp_i2c.c]"]
  node_pins["Board Configuration<br/>[bsp_pins.h]"]
end

subgraph group_platform["Device Platform"]
  node_lcd["LCD Hardware"]
  node_buttons["Physical Buttons"]
  node_codec["ES8311 Codec"]
  node_battery["Battery Gauge"]
  node_wifi["Wi-Fi Radio"]
  node_ble["BLE Peer"]
  node_sleep["ESP Sleep"]
end

node_maker(("Device User"))

node_maker -->|"presses"| node_buttons
node_buttons -->|"ADC input"| node_buttonbsp
node_buttonbsp -->|"button events"| node_input
node_entry -->|"queues input"| node_input
node_input -->|"dispatches"| node_navigation
node_navigation -->|"selects demo"| node_entry
node_entry -->|"builds screens"| node_pixelui
node_pixelui -->|"uses display"| node_displaybsp
node_displaybsp -->|"drives"| node_lcd
node_displaydemo -->|"renders"| node_pixelui
node_buttondemo -->|"reads buttons"| node_buttonbsp
node_audiodemo -->|"uses audio"| node_audiobsp
node_batterydemo -->|"reads charge"| node_batterybsp
node_wifidemo -->|"demonstrates Wi-Fi"| node_wifi
node_bledemo -->|"advertises"| node_ble
node_radiodemo -->|"uses radio"| node_wifi
node_radiodemo -->|"uses radio"| node_ble
node_sleepdemo -->|"suspends"| node_batterybsp
node_sleepdemo -->|"suspends"| node_audiobsp
node_sleepdemo -->|"prepares bus"| node_i2cbsp
node_sleepdemo -->|"suspends display"| node_displaybsp
node_sleepdemo -->|"enters sleep"| node_sleep
node_audiobsp -->|"uses control bus"| node_i2cbsp
node_batterybsp -->|"uses shared bus"| node_i2cbsp
node_i2cbsp -->|"control bus"| node_codec
node_i2cbsp -->|"control bus"| node_battery
node_buttonbsp -->|"uses pin settings"| node_pins
node_displaybsp -->|"uses pin settings"| node_pins
node_audiobsp -->|"uses pin settings"| node_pins

click node_entry "https://github.com/folotoy/ai-passport/blob/main/main/main.c"
click node_input "https://github.com/folotoy/ai-passport/blob/main/main/main.c"
click node_navigation "https://github.com/folotoy/ai-passport/blob/main/main/demo_navigation.c"
click node_pixelui "https://github.com/folotoy/ai-passport/blob/main/main/ui_pixel.c"
click node_displaydemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_display.c"
click node_buttondemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_button.c"
click node_audiodemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_audio.c"
click node_batterydemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_battery.c"
click node_wifidemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_wifi.c"
click node_bledemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_ble.c"
click node_radiodemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_radio.c"
click node_sleepdemo "https://github.com/folotoy/ai-passport/blob/main/main/demo_low_power.c"
click node_displaybsp "https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_display.c"
click node_buttonbsp "https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_button.c"
click node_audiobsp "https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_audio.c"
click node_batterybsp "https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_battery.c"
click node_i2cbsp "https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_i2c.c"
click node_pins "https://github.com/folotoy/ai-passport/blob/main/components/bsp/include/bsp_pins.h"

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_entry,node_input,node_navigation,node_pixelui,node_maker toneBlue
class node_displaydemo,node_buttondemo,node_audiodemo,node_batterydemo,node_wifidemo,node_bledemo,node_radiodemo,node_sleepdemo toneAmber
class node_displaybsp,node_buttonbsp,node_audiobsp,node_batterybsp,node_i2cbsp,node_pins toneMint
class node_lcd,node_buttons,node_codec,node_battery,node_wifi,node_ble,node_sleep toneRose
```

## Components

### Demo Application

- [Firmware Entry](https://github.com/folotoy/ai-passport/blob/main/main/main.c): `main/main.c`
- [Input Dispatch](https://github.com/folotoy/ai-passport/blob/main/main/main.c): `main/main.c`
- [Menu Navigation](https://github.com/folotoy/ai-passport/blob/main/main/demo_navigation.c): `main/demo_navigation.c`
- [Pixel UI](https://github.com/folotoy/ai-passport/blob/main/main/ui_pixel.c): `main/ui_pixel.c`

### Hardware Demos

- [Display Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_display.c): `main/demo_display.c`
- [Button Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_button.c): `main/demo_button.c`
- [Audio Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_audio.c): `main/demo_audio.c`
- [Battery Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_battery.c): `main/demo_battery.c`
- [Wi-Fi Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_wifi.c): `main/demo_wifi.c`
- [BLE Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_ble.c): `main/demo_ble.c`
- [Radio Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_radio.c): `main/demo_radio.c`
- [Low Power Demo](https://github.com/folotoy/ai-passport/blob/main/main/demo_low_power.c): `main/demo_low_power.c`

### Board Support

- [Display BSP](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_display.c): `components/bsp/src/bsp_display.c`
- [Button BSP](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_button.c): `components/bsp/src/bsp_button.c`
- [Audio BSP](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_audio.c): `components/bsp/src/bsp_audio.c`
- [Battery BSP](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_battery.c): `components/bsp/src/bsp_battery.c`
- [Shared I²C](https://github.com/folotoy/ai-passport/blob/main/components/bsp/src/bsp_i2c.c): `components/bsp/src/bsp_i2c.c`
- [Board Configuration](https://github.com/folotoy/ai-passport/blob/main/components/bsp/include/bsp_pins.h): `components/bsp/include/bsp_pins.h`

### Device Platform

- **LCD Hardware**
- **Physical Buttons**
- **ES8311 Codec**
- **Battery Gauge**
- **Wi-Fi Radio**
- **BLE Peer**
- **ESP Sleep**

### Other components

- **Device User**

## Connections

- Device User → Physical Buttons: presses
- Physical Buttons → Button BSP: ADC input
- Button BSP → Input Dispatch: button events
- Firmware Entry → Input Dispatch: queues input
- Input Dispatch → Menu Navigation: dispatches
- Menu Navigation → Firmware Entry: selects demo
- Firmware Entry → Pixel UI: builds screens
- Pixel UI → Display BSP: uses display
- Display BSP → LCD Hardware: drives
- Display Demo → Pixel UI: renders
- Button Demo → Button BSP: reads buttons
- Audio Demo → Audio BSP: uses audio
- Battery Demo → Battery BSP: reads charge
- Wi-Fi Demo → Wi-Fi Radio: demonstrates Wi-Fi
- BLE Demo → BLE Peer: advertises
- Radio Demo → Wi-Fi Radio: uses radio
- Radio Demo → BLE Peer: uses radio
- Low Power Demo → Battery BSP: suspends
- Low Power Demo → Audio BSP: suspends
- Low Power Demo → Shared I²C: prepares bus
- Low Power Demo → Display BSP: suspends display
- Low Power Demo → ESP Sleep: enters sleep
- Audio BSP → Shared I²C: uses control bus
- Battery BSP → Shared I²C: uses shared bus
- Shared I²C → ES8311 Codec: control bus
- Shared I²C → Battery Gauge: control bus
- Button BSP → Board Configuration: uses pin settings
- Display BSP → Board Configuration: uses pin settings
- Audio BSP → Board Configuration: uses pin settings