# bigbrodude6119/flipper-zero-friend-finder architecture

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

- Interactive diagram: https://gitdiagram.com/bigbrodude6119/flipper-zero-friend-finder
- Repository: https://github.com/bigbrodude6119/flipper-zero-friend-finder

## Overview

Friend Finder is a Flipper Zero app paired with ESP32 WiFi firmware. The main workflow is: the user starts listening, the board scans nearby WiFi traffic and reports peers over UART, the app parses and tracks them, and the user can inspect the friend history or send a selected payload back through the board. The README also documents harmless built-in/custom payloads and communication with other Friend Finder devices. Source excerpts establish the app’s scene dispatch and parts of the sending flow; some firmware and scene links rely on the SOURCE INDEX or README, so unsampled internals are not expanded.

Main entry points: [`src/uart.c`](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/uart.c) (UART link), [`src/persistence.c`](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/persistence.c) (Persistence), [`src/protocol.c`](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/protocol.c) (Line protocol), [`src/scene_send_menu.c`](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_send_menu.c) (Payload menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flipper app"]
  node_entry["App and scenes<br/>[main.c]"]
  node_main_scene["Main screen<br/>[scene_main_menu.c]"]
  node_listen_scene["Listen screen<br/>[scene_listen.c]"]
  node_monitor_scene["Monitor screen<br/>[scene_monitor.c]"]
  node_friend_detail["Friend details"]
  node_settings["Settings<br/>[scene_settings.c]"]
end

subgraph group_peer["Peer discovery"]
  node_uart_app["UART link<br/>[uart.c]"]
  node_protocol["Line protocol<br/>[protocol.c]"]
  node_json["JSON validation<br/>[safe_json.c]"]
  node_device_model["Peer tracking<br/>[pwnagotchi.c]"]
end

subgraph group_payload["Payload sending"]
  node_send_menu["Payload menu<br/>[scene_send_menu.c]"]
  node_send_options["Send options"]
  node_sending["Sending session<br/>[scene_sending.c]"]
  node_catalog["Payload catalog<br/>[payload_loader.c]"]
  node_builtins["Built-in payloads<br/>[payloads.c]"]
end

subgraph group_firmware["ESP32 firmware"]
  node_wifi["WiFi scanning<br/>[wifi_sniffer.c]"]
  node_board_protocol["Board UART protocol<br/>[uart_proto.c]"]
  node_beacon["Beacon injection<br/>[beacon_inject.c]"]
end

subgraph group_state["Local state"]
  node_persistence[("Persistence<br/>[persistence.c]")]
end

node_user(("Flipper user"))
node_peer_devices(("Nearby peers"))

node_user -->|"starts app"| node_entry
node_entry -->|"dispatches scenes"| node_main_scene
node_user -.->|"starts listening"| node_listen_scene
node_listen_scene -.->|"requests scanning"| node_uart_app
node_main_scene -->|"reads link state"| node_uart_app
node_peer_devices -->|"emit WiFi traffic"| node_wifi
node_wifi -->|"reports detections"| node_board_protocol
node_board_protocol -->|"sends UART lines"| node_uart_app
node_uart_app -->|"processes received lines"| node_protocol
node_protocol -->|"validates peer JSON"| node_json
node_protocol -->|"updates peer records"| node_device_model
node_device_model -->|"updates friend history"| node_persistence
node_user -.->|"inspects peers"| node_friend_detail
node_user -.->|"monitors scanning"| node_monitor_scene
node_user -.->|"configures app"| node_settings
node_settings -->|"saves settings"| node_persistence
node_user -.->|"chooses payload"| node_send_menu
node_send_menu -->|"loads choices"| node_catalog
node_catalog -->|"loads built-ins"| node_builtins
node_send_menu -->|"loads profiles"| node_persistence
node_user -.->|"sets send options"| node_send_options
node_send_options -->|"saves options"| node_persistence
node_send_menu -.->|"opens session"| node_sending
node_sending -->|"builds payload JSON"| node_catalog
node_sending -->|"saves active profile"| node_persistence
node_sending -->|"sends payload command"| node_protocol
node_protocol -->|"transmits command"| node_uart_app
node_uart_app -.->|"sends UART command"| node_board_protocol
node_board_protocol -->|"dispatches injection"| node_beacon
node_beacon -.->|"broadcasts payload"| node_peer_devices
node_persistence -->|"loads saved data"| node_entry

click node_entry "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/main.c"
click node_main_scene "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_main_menu.c"
click node_listen_scene "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_listen.c"
click node_monitor_scene "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_monitor.c"
click node_friend_detail "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_device_detail.c"
click node_settings "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_settings.c"
click node_send_menu "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_send_menu.c"
click node_send_options "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_send_options.c"
click node_sending "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_sending.c"
click node_catalog "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/payload_loader.c"
click node_builtins "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/payloads.c"
click node_uart_app "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/uart.c"
click node_protocol "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/protocol.c"
click node_json "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/safe_json.c"
click node_device_model "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/pwnagotchi.c"
click node_persistence "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/persistence.c"
click node_wifi "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/wifi_sniffer.c"
click node_board_protocol "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/uart_proto.c"
click node_beacon "https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/beacon_inject.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_entry,node_main_scene,node_listen_scene,node_monitor_scene,node_friend_detail,node_settings,node_user toneBlue
class node_uart_app,node_protocol,node_json,node_device_model toneAmber
class node_send_menu,node_send_options,node_sending,node_catalog,node_builtins toneMint
class node_wifi,node_board_protocol,node_beacon toneRose
class node_persistence,node_peer_devices toneIndigo
```

## Components

### Flipper app

- [App and scenes](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/main.c): `main.c`
- [Main screen](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_main_menu.c): `src/scene_main_menu.c`
- [Listen screen](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_listen.c): `src/scene_listen.c`
- [Monitor screen](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_monitor.c): `src/scene_monitor.c`
- [Friend details](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_device_detail.c): `src/scene_device_detail.c`
- [Settings](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_settings.c): `src/scene_settings.c`

### Peer discovery

- [UART link](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/uart.c): `src/uart.c`
- [Line protocol](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/protocol.c): `src/protocol.c`
- [JSON validation](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/safe_json.c): `src/safe_json.c`
- [Peer tracking](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/pwnagotchi.c): `src/pwnagotchi.c`

### Payload sending

- [Payload menu](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_send_menu.c): `src/scene_send_menu.c`
- [Send options](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_send_options.c): `src/scene_send_options.c`
- [Sending session](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/scene_sending.c): `src/scene_sending.c`
- [Payload catalog](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/payload_loader.c): `src/payload_loader.c`
- [Built-in payloads](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/payloads.c): `src/payloads.c`

### ESP32 firmware

- [WiFi scanning](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/wifi_sniffer.c): `esp32_firmware/main/wifi_sniffer.c`
- [Board UART protocol](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/uart_proto.c): `esp32_firmware/main/uart_proto.c`
- [Beacon injection](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/esp32_firmware/main/beacon_inject.c): `esp32_firmware/main/beacon_inject.c`

### Local state

- [Persistence](https://github.com/bigbrodude6119/flipper-zero-friend-finder/blob/main/src/persistence.c): `src/persistence.c`

### Other components

- **Flipper user**
- **Nearby peers**

## Connections

- Flipper user → App and scenes: starts app (evidence: `README.md`)
- App and scenes → Main screen: dispatches scenes (evidence: `main.c`)
- Flipper user → Listen screen: starts listening
- Listen screen → UART link: requests scanning
- Main screen → UART link: reads link state (evidence: `src/scene_main_menu.c`)
- Nearby peers → WiFi scanning: emit WiFi traffic (evidence: `README.md`)
- WiFi scanning → Board UART protocol: reports detections (evidence: `esp32_firmware/main/wifi_sniffer.c`)
- Board UART protocol → UART link: sends UART lines (evidence: `esp32_firmware/main/uart_proto.c`)
- UART link → Line protocol: processes received lines (evidence: `src/uart.c`)
- Line protocol → JSON validation: validates peer JSON (evidence: `src/protocol.c`)
- Line protocol → Peer tracking: updates peer records (evidence: `src/protocol.c`)
- Peer tracking → Persistence: updates friend history (evidence: `src/pwnagotchi.c`)
- Flipper user → Friend details: inspects peers
- Flipper user → Monitor screen: monitors scanning
- Flipper user → Settings: configures app
- Settings → Persistence: saves settings (evidence: `src/scene_settings.c`)
- Flipper user → Payload menu: chooses payload
- Payload menu → Payload catalog: loads choices (evidence: `src/scene_send_menu.c`)
- Payload catalog → Built-in payloads: loads built-ins (evidence: `src/payload_loader.c`)
- Payload menu → Persistence: loads profiles (evidence: `src/scene_send_menu.c`)
- Flipper user → Send options: sets send options
- Send options → Persistence: saves options (evidence: `src/scene_send_options.c`)
- Payload menu → Sending session: opens session
- Sending session → Payload catalog: builds payload JSON (evidence: `src/scene_sending.c`)
- Sending session → Persistence: saves active profile (evidence: `src/scene_sending.c`)
- Sending session → Line protocol: sends payload command (evidence: `src/scene_sending.c`)
- Line protocol → UART link: transmits command (evidence: `src/protocol.c`)
- UART link → Board UART protocol: sends UART command
- Board UART protocol → Beacon injection: dispatches injection (evidence: `esp32_firmware/main/uart_proto.c`)
- Beacon injection → Nearby peers: broadcasts payload (evidence: `README.md`)
- Persistence → App and scenes: loads saved data (evidence: `main.c`)
