# theowenyoung/ai-passport architecture

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

- Interactive diagram: https://gitdiagram.com/theowenyoung/ai-passport
- Repository: https://github.com/theowenyoung/ai-passport

## Overview

FoloToy AI Passport is an open wearable-device firmware baseline; the README describes `main` as a runnable hardware-test demo, not a finished application. The user-facing flow is button input → menu navigation → a selected hardware demo → device feedback or a radio/sleep result. The graph preserves the documented display, button, audio, battery, Wi-Fi, BLE, and low-power demos plus the BSP and shared UI layer. Several demo and BSP relationships come from the SOURCE INDEX; links not established by shown calls are omitted or marked unverified.

Main entry points: [`main/main.c`](https://github.com/theowenyoung/ai-passport/blob/main/main/main.c) (Firmware lifecycle), [`main/demo_low_power.c`](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_low_power.c) (Low-power demo), [`main/ui_pixel.c`](https://github.com/theowenyoung/ai-passport/blob/main/main/ui_pixel.c) (Pixel UI helpers), [`components/bsp/src/bsp_display.c`](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_display.c) (Display driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Demo application"]
  node_firmware["Firmware lifecycle<br/>[main.c]"]
  node_navigation["Menu navigation<br/>[demo_navigation.c]"]
  node_display_demo["Display demo<br/>[demo_display.c]"]
  node_button_demo["Button demo<br/>[demo_button.c]"]
  node_audio_demo["Audio demo<br/>[demo_audio.c]"]
  node_battery_demo["Battery demo<br/>[demo_battery.c]"]
  node_sleep_demo["Low-power demo<br/>[demo_low_power.c]"]
end

subgraph group_hardware["Board support"]
  node_buttons["Button input<br/>[bsp_button.c]"]
  node_display["Display driver<br/>[bsp_display.c]"]
  node_audio["Audio driver<br/>[bsp_audio.c]"]
  node_battery["Battery sensing<br/>[bsp_battery.c]"]
  node_i2c["Shared I2C<br/>[bsp_i2c.c]"]
  node_pins["Board pin map<br/>[bsp_pins.h]"]
  node_lvgl_display["LVGL display port<br/>[bsp_display_lvgl.c]"]
end

subgraph group_shared["Shared UI"]
  node_ui["Pixel UI helpers<br/>[ui_pixel.c]"]
end

subgraph group_radio["Radio services"]
  node_wifi_demo["Wi-Fi scan<br/>[demo_wifi.c]"]
  node_ble_demo["BLE advertising<br/>[demo_ble.c]"]
  node_radio_setup["Radio setup<br/>[demo_radio.c]"]
end

node_user(("Device user"))

node_user -->|"presses"| node_buttons
node_buttons -.->|"sends events"| node_firmware
node_firmware -->|"routes input"| node_navigation
node_firmware -.->|"dispatches demo"| node_display_demo
node_firmware -.->|"dispatches demo"| node_button_demo
node_firmware -.->|"dispatches demo"| node_audio_demo
node_firmware -.->|"dispatches demo"| node_battery_demo
node_firmware -.->|"dispatches demo"| node_wifi_demo
node_firmware -.->|"dispatches demo"| node_ble_demo
node_firmware -.->|"dispatches demo"| node_sleep_demo
node_display_demo -->|"uses helpers"| node_ui
node_button_demo -->|"uses helpers"| node_ui
node_audio_demo -->|"plays and records"| node_audio
node_audio_demo -->|"locks UI"| node_display
node_audio_demo -->|"uses helpers"| node_ui
node_battery_demo -->|"reads level"| node_battery
node_battery_demo -->|"uses helpers"| node_ui
node_wifi_demo -->|"prepares radio"| node_radio_setup
node_ble_demo -->|"uses setup"| node_radio_setup
node_wifi_demo -->|"shows results"| node_ui
node_ble_demo -->|"uses helpers"| node_ui
node_sleep_demo -->|"suspends audio"| node_audio
node_sleep_demo -->|"suspends gauge"| node_battery
node_sleep_demo -->|"suspends display"| node_display
node_sleep_demo -->|"releases bus"| node_i2c
node_sleep_demo -->|"updates status"| node_ui
node_buttons -->|"uses configuration"| node_pins
node_display -->|"uses configuration"| node_pins
node_audio -->|"uses configuration"| node_pins
node_audio -->|"uses bus"| node_i2c
node_battery -->|"uses configuration"| node_pins
node_battery -->|"uses bus"| node_i2c
node_lvgl_display -->|"adapts driver"| node_display
node_display -.->|"initializes port"| node_lvgl_display

click node_firmware "https://github.com/theowenyoung/ai-passport/blob/main/main/main.c"
click node_navigation "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_navigation.c"
click node_display_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_display.c"
click node_button_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_button.c"
click node_audio_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_audio.c"
click node_battery_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_battery.c"
click node_wifi_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_wifi.c"
click node_ble_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_ble.c"
click node_radio_setup "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_radio.c"
click node_sleep_demo "https://github.com/theowenyoung/ai-passport/blob/main/main/demo_low_power.c"
click node_buttons "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_button.c"
click node_display "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_display.c"
click node_audio "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_audio.c"
click node_battery "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_battery.c"
click node_i2c "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_i2c.c"
click node_pins "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/include/bsp_pins.h"
click node_ui "https://github.com/theowenyoung/ai-passport/blob/main/main/ui_pixel.c"
click node_lvgl_display "https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_display_lvgl.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_firmware,node_navigation,node_display_demo,node_button_demo,node_audio_demo,node_battery_demo,node_sleep_demo,node_user toneBlue
class node_buttons,node_display,node_audio,node_battery,node_i2c,node_pins,node_lvgl_display toneAmber
class node_ui toneMint
class node_wifi_demo,node_ble_demo,node_radio_setup toneRose
```

## Components

### Demo application

- [Firmware lifecycle](https://github.com/theowenyoung/ai-passport/blob/main/main/main.c): `main/main.c`
- [Menu navigation](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_navigation.c): `main/demo_navigation.c`
- [Display demo](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_display.c): `main/demo_display.c`
- [Button demo](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_button.c): `main/demo_button.c`
- [Audio demo](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_audio.c): `main/demo_audio.c`
- [Battery demo](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_battery.c): `main/demo_battery.c`
- [Low-power demo](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_low_power.c): `main/demo_low_power.c`

### Board support

- [Button input](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_button.c): `components/bsp/src/bsp_button.c`
- [Display driver](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_display.c): `components/bsp/src/bsp_display.c`
- [Audio driver](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_audio.c): `components/bsp/src/bsp_audio.c`
- [Battery sensing](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_battery.c): `components/bsp/src/bsp_battery.c`
- [Shared I2C](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_i2c.c): `components/bsp/src/bsp_i2c.c`
- [Board pin map](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/include/bsp_pins.h): `components/bsp/include/bsp_pins.h`
- [LVGL display port](https://github.com/theowenyoung/ai-passport/blob/main/components/bsp/src/bsp_display_lvgl.c): `components/bsp/src/bsp_display_lvgl.c`

### Shared UI

- [Pixel UI helpers](https://github.com/theowenyoung/ai-passport/blob/main/main/ui_pixel.c): `main/ui_pixel.c`

### Radio services

- [Wi-Fi scan](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_wifi.c): `main/demo_wifi.c`
- [BLE advertising](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_ble.c): `main/demo_ble.c`
- [Radio setup](https://github.com/theowenyoung/ai-passport/blob/main/main/demo_radio.c): `main/demo_radio.c`

### Other components

- **Device user**

## Connections

- Device user → Button input: presses
- Button input → Firmware lifecycle: sends events
- Firmware lifecycle → Menu navigation: routes input (evidence: `main/main.c`)
- Firmware lifecycle → Display demo: dispatches demo
- Firmware lifecycle → Button demo: dispatches demo
- Firmware lifecycle → Audio demo: dispatches demo
- Firmware lifecycle → Battery demo: dispatches demo
- Firmware lifecycle → Wi-Fi scan: dispatches demo
- Firmware lifecycle → BLE advertising: dispatches demo
- Firmware lifecycle → Low-power demo: dispatches demo
- Display demo → Pixel UI helpers: uses helpers (evidence: `main/demo_display.c`)
- Button demo → Pixel UI helpers: uses helpers (evidence: `main/demo_button.c`)
- Audio demo → Audio driver: plays and records (evidence: `main/demo_audio.c`)
- Audio demo → Display driver: locks UI (evidence: `main/demo_audio.c`)
- Audio demo → Pixel UI helpers: uses helpers (evidence: `main/demo_audio.c`)
- Battery demo → Battery sensing: reads level (evidence: `main/demo_battery.c`)
- Battery demo → Pixel UI helpers: uses helpers (evidence: `main/demo_battery.c`)
- Wi-Fi scan → Radio setup: prepares radio (evidence: `main/demo_wifi.c`)
- BLE advertising → Radio setup: uses setup (evidence: `main/demo_ble.c`)
- Wi-Fi scan → Pixel UI helpers: shows results (evidence: `main/demo_wifi.c`)
- BLE advertising → Pixel UI helpers: uses helpers (evidence: `main/demo_ble.c`)
- Low-power demo → Audio driver: suspends audio (evidence: `main/demo_low_power.c`)
- Low-power demo → Battery sensing: suspends gauge (evidence: `main/demo_low_power.c`)
- Low-power demo → Display driver: suspends display (evidence: `main/demo_low_power.c`)
- Low-power demo → Shared I2C: releases bus (evidence: `main/demo_low_power.c`)
- Low-power demo → Pixel UI helpers: updates status (evidence: `main/demo_low_power.c`)
- Button input → Board pin map: uses configuration (evidence: `components/bsp/src/bsp_button.c`)
- Display driver → Board pin map: uses configuration (evidence: `components/bsp/src/bsp_display.c`)
- Audio driver → Board pin map: uses configuration (evidence: `components/bsp/src/bsp_audio.c`)
- Audio driver → Shared I2C: uses bus (evidence: `components/bsp/src/bsp_audio.c`)
- Battery sensing → Board pin map: uses configuration (evidence: `components/bsp/src/bsp_battery.c`)
- Battery sensing → Shared I2C: uses bus (evidence: `components/bsp/src/bsp_battery.c`)
- LVGL display port → Display driver: adapts driver (evidence: `components/bsp/src/bsp_display_lvgl.c`)
- Display driver → LVGL display port: initializes port
