# kenhtaymay/openhaystack architecture

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

## Overview

OpenHaystack is a macOS application and firmware suite for creating Bluetooth tracking accessories and viewing their latest Find My locations. The main workflow configures an accessory and its key, deploys its public key to hardware, then uses authenticated report retrieval and private-key decryption to display locations. The README also documents firmware-based beaconing and a cross-platform mobile app. Edges are limited to documented README flows or source-index references; firmware-to-Apple discovery and mobile runtime internals are not sampled.

Main entry points: [`OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift`](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift) (Accessory controller), [`OpenHaystack/OpenHaystack/FindMy/FindMyController.swift`](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/FindMyController.swift) (Report retrieval), [`OpenHaystack/OpenHaystack/HaystackApp/Model/Accessory.swift`](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Model/Accessory.swift) (Accessory and keys), [`OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift`](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift) (Main interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accessory["Accessory management"]
  node_mainui["Main interface"]
  node_accessoryctl["Accessory controller"]
  node_accessory["Accessory and keys<br/>[Accessory.swift]"]
  node_keychain[("Private key store")]
  node_files["File operations<br/>[FileManager.swift]"]
end

subgraph group_location["Find My reports"]
  node_mailmanager["Mail plugin manager"]
  node_mailplugin["Apple Mail plugin"]
  node_anisette["Account authentication"]
  node_findmy["Report retrieval"]
  node_decrypt["Report decryption"]
  node_map["Location map"]
end

subgraph group_deployment["Hardware deployment"]
  node_microbit["micro:bit deployment"]
  node_esp32["ESP32 deployment"]
  node_nrf["nRF deployment"]
  node_microfw["micro:bit firmware<br/>[main.c]"]
  node_espfw["ESP32 firmware"]
  node_linuxhci["Linux HCI beacon<br/>[HCI.py]"]
end

subgraph group_platform["Mobile app"]
  node_mobile["OpenHaystack Mobile"]
end

node_user(("Accessory owner"))
node_apple[("Apple Find My service")]

node_user -->|"manages accessories"| node_mainui
node_mainui -->|"uses"| node_accessoryctl
node_accessoryctl -->|"creates and updates"| node_accessory
node_accessoryctl -->|"stores keys"| node_keychain
node_accessoryctl -->|"requests reports"| node_findmy
node_accessory -->|"keeps private key"| node_keychain
node_mainui -->|"manages plugin"| node_mailmanager
node_mailmanager -->|"copies plugin files"| node_files
node_mailplugin -.->|"provides account data"| node_anisette
node_anisette -->|"requests authentication data"| node_mailplugin
node_anisette -.->|"supplies search token"| node_findmy
node_findmy -->|"queries reports"| node_apple
node_findmy -->|"decrypts reports"| node_decrypt
node_mainui -->|"displays locations"| node_map
node_findmy -.->|"provides latest locations"| node_map
node_accessoryctl -.->|"deploys accessory"| node_microbit
node_accessoryctl -.->|"deploys accessory"| node_esp32
node_accessoryctl -.->|"deploys accessory"| node_nrf
node_microbit -->|"writes firmware"| node_microfw
node_microbit -->|"patches public key"| node_accessory
node_esp32 -->|"uses accessory key"| node_accessory
node_esp32 -.->|"deploys firmware"| node_espfw
node_accessory -->|"provides accessory data"| node_nrf
node_microfw -.->|"broadcasts BLE beacon"| node_apple
node_espfw -.->|"broadcasts BLE beacon"| node_apple
node_linuxhci -.->|"broadcasts BLE beacon"| node_apple
node_user -.->|"uses mobile app"| node_mobile

click node_mainui "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift"
click node_accessoryctl "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift"
click node_accessory "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Model/Accessory.swift"
click node_keychain "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/KeychainController.swift"
click node_files "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/FileManager.swift"
click node_mailmanager "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Mail%20Plugin/MailPluginManager.swift"
click node_mailplugin "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystackMail/OpenHaystackPluginService.h"
click node_anisette "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/AnisetteDataManager.swift"
click node_findmy "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/FindMyController.swift"
click node_decrypt "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/DecryptReports.swift"
click node_map "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/AccessoryMapView.swift"
click node_microbit "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/MicrobitController.swift"
click node_esp32 "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/ESP32Controller.swift"
click node_nrf "https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/NRFController.swift"
click node_microfw "https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/Microbit_v1/offline-finding/main.c"
click node_espfw "https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/ESP32/main/openhaystack_main.c"
click node_linuxhci "https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/Linux_HCI/HCI.py"
click node_mobile "https://github.com/kenhtaymay/openhaystack/tree/main/openhaystack-mobile"

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_mainui,node_accessoryctl,node_accessory,node_keychain,node_files toneBlue
class node_mailmanager,node_mailplugin,node_anisette,node_findmy,node_decrypt,node_map,node_apple toneAmber
class node_microbit,node_esp32,node_nrf,node_microfw,node_espfw,node_linuxhci toneMint
class node_mobile toneRose
class node_user toneIndigo
```

## Components

### Accessory management

- [Main interface](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift): `OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift`
- [Accessory controller](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift): `OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift`
- [Accessory and keys](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Model/Accessory.swift): `OpenHaystack/OpenHaystack/HaystackApp/Model/Accessory.swift`
- [Private key store](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/KeychainController.swift): `OpenHaystack/OpenHaystack/HaystackApp/KeychainController.swift`
- [File operations](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/FileManager.swift): `OpenHaystack/OpenHaystack/HaystackApp/FileManager.swift`

### Find My reports

- [Mail plugin manager](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Mail%20Plugin/MailPluginManager.swift): `OpenHaystack/OpenHaystack/HaystackApp/Mail Plugin/MailPluginManager.swift`
- [Apple Mail plugin](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystackMail/OpenHaystackPluginService.h): `OpenHaystack/OpenHaystackMail/OpenHaystackPluginService.h`
- [Account authentication](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/AnisetteDataManager.swift): `OpenHaystack/OpenHaystack/AnisetteDataManager.swift`
- [Report retrieval](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/FindMyController.swift): `OpenHaystack/OpenHaystack/FindMy/FindMyController.swift`
- [Report decryption](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/DecryptReports.swift): `OpenHaystack/OpenHaystack/FindMy/DecryptReports.swift`
- [Location map](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/AccessoryMapView.swift): `OpenHaystack/OpenHaystack/HaystackApp/Views/AccessoryMapView.swift`

### Hardware deployment

- [micro:bit deployment](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/MicrobitController.swift): `OpenHaystack/OpenHaystack/HaystackApp/MicrobitController.swift`
- [ESP32 deployment](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/ESP32Controller.swift): `OpenHaystack/OpenHaystack/HaystackApp/ESP32Controller.swift`
- [nRF deployment](https://github.com/kenhtaymay/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/NRFController.swift): `OpenHaystack/OpenHaystack/HaystackApp/NRFController.swift`
- [micro:bit firmware](https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/Microbit_v1/offline-finding/main.c): `Firmware/Microbit_v1/offline-finding/main.c`
- [ESP32 firmware](https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/ESP32/main/openhaystack_main.c): `Firmware/ESP32/main/openhaystack_main.c`
- [Linux HCI beacon](https://github.com/kenhtaymay/openhaystack/blob/main/Firmware/Linux_HCI/HCI.py): `Firmware/Linux_HCI/HCI.py`

### Mobile app

- [OpenHaystack Mobile](https://github.com/kenhtaymay/openhaystack/tree/main/openhaystack-mobile): `openhaystack-mobile`

### Other components

- **Accessory owner**
- **Apple Find My service**

## Connections

- Accessory owner → Main interface: manages accessories
- Main interface → Accessory controller: uses (evidence: `OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift`)
- Accessory controller → Accessory and keys: creates and updates (evidence: `OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift`)
- Accessory controller → Private key store: stores keys (evidence: `OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift`)
- Accessory controller → Report retrieval: requests reports (evidence: `OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift`)
- Accessory and keys → Private key store: keeps private key (evidence: `OpenHaystack/OpenHaystack/HaystackApp/KeychainController.swift`)
- Main interface → Mail plugin manager: manages plugin (evidence: `OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift`)
- Mail plugin manager → File operations: copies plugin files (evidence: `OpenHaystack/OpenHaystack/HaystackApp/Mail Plugin/MailPluginManager.swift`)
- Apple Mail plugin → Account authentication: provides account data
- Account authentication → Apple Mail plugin: requests authentication data (evidence: `OpenHaystack/OpenHaystack/AnisetteDataManager.swift`)
- Account authentication → Report retrieval: supplies search token
- Report retrieval → Apple Find My service: queries reports
- Report retrieval → Report decryption: decrypts reports (evidence: `OpenHaystack/OpenHaystack/FindMy/FindMyController.swift`)
- Main interface → Location map: displays locations (evidence: `OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift`)
- Report retrieval → Location map: provides latest locations
- Accessory controller → micro:bit deployment: deploys accessory
- Accessory controller → ESP32 deployment: deploys accessory
- Accessory controller → nRF deployment: deploys accessory
- micro:bit deployment → micro:bit firmware: writes firmware (evidence: `OpenHaystack/OpenHaystack/HaystackApp/MicrobitController.swift`)
- micro:bit deployment → Accessory and keys: patches public key (evidence: `OpenHaystack/OpenHaystack/HaystackApp/MicrobitController.swift`)
- ESP32 deployment → Accessory and keys: uses accessory key (evidence: `OpenHaystack/OpenHaystack/HaystackApp/ESP32Controller.swift`)
- ESP32 deployment → ESP32 firmware: deploys firmware
- Accessory and keys → nRF deployment: provides accessory data (evidence: `OpenHaystack/OpenHaystack/HaystackApp/NRFController.swift`)
- micro:bit firmware → Apple Find My service: broadcasts BLE beacon
- ESP32 firmware → Apple Find My service: broadcasts BLE beacon
- Linux HCI beacon → Apple Find My service: broadcasts BLE beacon
- Accessory owner → OpenHaystack Mobile: uses mobile app
