# seemoo-lab/openhaystack architecture

> Architecture diagram of the GitHub repository seemoo-lab/openhaystack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seemoo-lab/openhaystack
- Repository: https://github.com/seemoo-lab/openhaystack

## Overview

##### Main Components

a. Core Components:
- macOS Application (OpenHaystack)
- Mail Plugin (OpenHaystackMail)
- Mobile Application (Flutter-based)
- Firmware Components (ESP32, Microbit, Linux HCI)
- Apple's Find My Network (external system)

b. Data Components:
- Local Storage (Keychain for keys)
- Apple's Location Reports Database
- Device Configuration Storage

- macOS App      |     | Mobile App      |
- (SwiftUI/AppKit)|     | (Flutter)       |

- Mail Plugin   |     | Reports Fetcher  |
- (Authentication) |  | (Location Data)   |

- ESP32    |    | Microbit |    | Linux    |
- Firmware |    | Firmware |    | HCI      |

- Find My Network   |    | Apple Location   |
- (iPhone Network)  |    | Reports Server   |

##### Data Flow Indicators

- Bluetooth advertisements from accessories to Find My Network
- Encrypted location reports from iPhones to Apple's servers
- Authentication flow from Mail Plugin to Apple's servers
- Location data retrieval from servers to applications
- Key deployment from applications to accessories

- Key Management   |
- Public Keys    |
- Private Keys   |
- Keychain Store |

- Location Process |
- Encryption     |
- Decryption     |
- Report Parsing |

##### Integration Points

Interfaces between:
- Mail plugin and Apple's authentication
- Applications and firmware deployment
- Accessories and Find My network
- Applications and location report retrieval

##### Security Boundaries

- Local device security (keychain)
- Network security (encrypted reports)
- Device security (firmware)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef firmware fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,color:white

    %% User Interface Layer
    subgraph UI
        MacOS["macOS Application\n(SwiftUI/AppKit)"]
        Mobile["Mobile Application\n(Flutter)"]
        MainView["Main UI View"]
        Settings["Settings View"]
        Dashboard["Mobile Dashboard"]
    end

    %% Core Services Layer
    subgraph CoreServices
        MailPlugin["Mail Plugin\n(Authentication)"]
        ReportsFetcher["Reports Fetcher"]
        KeyManagement["Key Management"]
        LocationProcess["Location Processing"]
        AccessoryCtrl["Accessory Controller"]
        BluetoothScanner["Bluetooth Scanner"]
    end

    %% Firmware Layer
    subgraph Firmware
        ESP32["ESP32 Firmware"]
        Microbit["Microbit Firmware"]
        LinuxHCI["Linux HCI"]
    end

    %% External Systems
    subgraph External
        FindMyNetwork["Find My Network"]
        AppleServers["Apple Location\nReports Server"]
    end

    %% Security Components
    subgraph Security
        BoringSSL["BoringSSL Integration"]
        KeyDecoder["Key Decoder"]
        Keychain["Keychain Storage"]
    end

    %% Relationships
    MacOS --> MailPlugin
    MacOS --> ReportsFetcher
    MacOS --> AccessoryCtrl
    Mobile --> ReportsFetcher
    Mobile --> AccessoryCtrl
    
    MailPlugin --> AppleServers
    ReportsFetcher --> AppleServers
    
    AccessoryCtrl --> ESP32
    AccessoryCtrl --> Microbit
    AccessoryCtrl --> LinuxHCI
    
    ESP32 --> FindMyNetwork
    Microbit --> FindMyNetwork
    LinuxHCI --> FindMyNetwork
    
    FindMyNetwork --> AppleServers
    
    KeyManagement --> Keychain
    LocationProcess --> KeyDecoder
    KeyDecoder --> BoringSSL

    %% Click events for component mapping
    click MacOS "https://github.com/seemoo-lab/openhaystack/tree/main/OpenHaystack/OpenHaystack"
    click MainView "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackMainView.swift"
    click Settings "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Views/OpenHaystackSettingsView.swift"
    click MailPlugin "https://github.com/seemoo-lab/openhaystack/tree/main/OpenHaystack/OpenHaystackMail"
    click Mobile "https://github.com/seemoo-lab/openhaystack/blob/main/openhaystack-mobile/lib/main.dart"
    click Dashboard "https://github.com/seemoo-lab/openhaystack/tree/main/openhaystack-mobile/lib/dashboard"
    click ESP32 "https://github.com/seemoo-lab/openhaystack/tree/main/Firmware/ESP32"
    click Microbit "https://github.com/seemoo-lab/openhaystack/tree/main/Firmware/Microbit_v1"
    click LinuxHCI "https://github.com/seemoo-lab/openhaystack/tree/main/Firmware/Linux_HCI"
    click ReportsFetcher "https://github.com/seemoo-lab/openhaystack/tree/main/OpenHaystack/OpenHaystack/ReportsFetcher"
    click KeyManagement "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/KeychainController.swift"
    click LocationProcess "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/DecryptReports.swift"
    click AccessoryCtrl "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/AccessoryController.swift"
    click BluetoothScanner "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/HaystackApp/Bluetooth/BluetoothAccessoryScanner.swift"
    click BoringSSL "https://github.com/seemoo-lab/openhaystack/tree/main/OpenHaystack/OpenHaystack/BoringSSL"
    click KeyDecoder "https://github.com/seemoo-lab/openhaystack/blob/main/OpenHaystack/OpenHaystack/FindMy/FindMyKeyDecoder.swift"

    %% Style applications
    class MacOS,Mobile,MainView,Settings,Dashboard ui
    class MailPlugin,ReportsFetcher,KeyManagement,LocationProcess,AccessoryCtrl,BluetoothScanner core
    class ESP32,Microbit,LinuxHCI firmware
    class FindMyNetwork,AppleServers external
    class BoringSSL,KeyDecoder,Keychain security
```
