# steamclock/bluejay architecture

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

- Interactive diagram: https://gitdiagram.com/steamclock/bluejay
- Repository: https://github.com/steamclock/bluejay

## Overview

Bluejay is a Swift framework for reliable Bluetooth LE communication with a single peripheral. Its main workflow is to scan for peripherals, connect, discover services and characteristics, then read, write, or listen for characteristic updates through a FIFO operation queue. It also supports connection observation, serialization, logging, and background restoration. The README documents these capabilities, but most implementation files were not sampled; links among those subsystems are therefore limited to documented behavior. The two demo apps illustrate a heart-sensor client and a virtual peripheral.

Main entry points: [`Bluejay/Bluejay/Bluejay.swift`](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Bluejay.swift) (Bluejay API), [`Bluejay/Bluejay/Queue.swift`](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Queue.swift) (FIFO operation queue), [`Bluejay/DittojayHeartSensorDemo/DittojayViewController.swift`](https://github.com/steamclock/bluejay/blob/master/Bluejay/DittojayHeartSensorDemo/DittojayViewController.swift) (Virtual BLE sensor), [`Bluejay/Bluejay/Scan.swift`](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Scan.swift) (Peripheral scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Bluejay runtime"]
  node_bluejay["Bluejay API<br/>[Bluejay.swift]"]
  node_queue["FIFO operation queue<br/>[Queue.swift]"]
end

subgraph group_ops["Peripheral operations"]
  node_scan["Peripheral scanning<br/>[Scan.swift]"]
  node_connection["Connection management<br/>[Connection.swift]"]
  node_discovery["Service discovery"]
  node_read["Characteristic reads"]
  node_write["Characteristic writes"]
  node_listen["Characteristic listening"]
  node_serialization["Data serialization<br/>[Receivable.swift]"]
end

subgraph group_restore["Events and restoration"]
  node_observers["Connection observers"]
  node_disconnect["Disconnect handling"]
  node_restoration["Background restoration"]
  node_logging["Logging observers<br/>[LogObserver.swift]"]
end

subgraph group_demos["Heart sensor demos"]
  node_clientdemo["Heart sensor client"]
  node_sensordemo["Sensor interaction UI"]
  node_virtualsensor["Virtual BLE sensor"]
  node_measurement["Heart-rate data"]
end

node_app(("Calling app"))
node_corebluetooth["CoreBluetooth"]

node_app -->|"calls API"| node_bluejay
node_bluejay -->|"starts scan"| node_scan
node_scan -->|"scans for"| node_corebluetooth
node_scan -->|"returns discoveries"| node_app
node_bluejay -->|"connects or disconnects"| node_connection
node_connection -->|"manages connection"| node_corebluetooth
node_connection -->|"schedules operations"| node_queue
node_queue -->|"runs operations"| node_discovery
node_queue -->|"runs operations"| node_read
node_queue -->|"runs operations"| node_write
node_queue -->|"runs operations"| node_listen
node_discovery -->|"discovers services"| node_corebluetooth
node_read -->|"reads characteristic"| node_corebluetooth
node_write -->|"writes characteristic"| node_corebluetooth
node_listen -->|"subscribes to updates"| node_corebluetooth
node_serialization -->|"decodes data"| node_read
node_serialization -->|"encodes data"| node_write
node_bluejay -->|"notifies events"| node_observers
node_bluejay -->|"notifies disconnection"| node_disconnect
node_bluejay -->|"supports restoration"| node_restoration
node_bluejay -->|"emits logs"| node_logging
node_clientdemo -->|"scans and connects"| node_bluejay
node_sensordemo -->|"reads and listens"| node_bluejay
node_sensordemo -->|"registers observers"| node_observers
node_virtualsensor -->|"advertises services"| node_corebluetooth
node_virtualsensor -->|"creates measurements"| node_measurement
node_virtualsensor -->|"publishes updates"| node_corebluetooth

click node_bluejay "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Bluejay.swift"
click node_queue "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Queue.swift"
click node_scan "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Scan.swift"
click node_connection "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Connection.swift"
click node_discovery "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/DiscoverService.swift"
click node_read "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ReadCharacteristic.swift"
click node_write "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/WriteCharacteristic.swift"
click node_listen "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ListenCharacteristic.swift"
click node_serialization "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Receivable.swift"
click node_observers "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ConnectionObserver.swift"
click node_disconnect "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/DisconnectHandler.swift"
click node_restoration "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/BackgroundRestorer.swift"
click node_logging "https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/LogObserver.swift"
click node_clientdemo "https://github.com/steamclock/bluejay/blob/master/Bluejay/BluejayHeartSensorDemo/ScanViewController.swift"
click node_sensordemo "https://github.com/steamclock/bluejay/blob/master/Bluejay/BluejayHeartSensorDemo/SensorViewController.swift"
click node_virtualsensor "https://github.com/steamclock/bluejay/blob/master/Bluejay/DittojayHeartSensorDemo/DittojayViewController.swift"
click node_measurement "https://github.com/steamclock/bluejay/blob/master/Bluejay/DittojayHeartSensorDemo/HeartRateMeasurement.swift"

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_bluejay,node_queue toneBlue
class node_scan,node_connection,node_discovery,node_read,node_write,node_listen,node_serialization toneAmber
class node_observers,node_disconnect,node_restoration,node_logging toneMint
class node_clientdemo,node_sensordemo,node_virtualsensor,node_measurement toneRose
class node_app,node_corebluetooth toneIndigo
```

## Components

### Bluejay runtime

- [Bluejay API](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Bluejay.swift): `Bluejay/Bluejay/Bluejay.swift`
- [FIFO operation queue](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Queue.swift): `Bluejay/Bluejay/Queue.swift`

### Peripheral operations

- [Peripheral scanning](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Scan.swift): `Bluejay/Bluejay/Scan.swift`
- [Connection management](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Connection.swift): `Bluejay/Bluejay/Connection.swift`
- [Service discovery](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/DiscoverService.swift): `Bluejay/Bluejay/DiscoverService.swift`
- [Characteristic reads](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ReadCharacteristic.swift): `Bluejay/Bluejay/ReadCharacteristic.swift`
- [Characteristic writes](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/WriteCharacteristic.swift): `Bluejay/Bluejay/WriteCharacteristic.swift`
- [Characteristic listening](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ListenCharacteristic.swift): `Bluejay/Bluejay/ListenCharacteristic.swift`
- [Data serialization](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/Receivable.swift): `Bluejay/Bluejay/Receivable.swift`

### Events and restoration

- [Connection observers](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/ConnectionObserver.swift): `Bluejay/Bluejay/ConnectionObserver.swift`
- [Disconnect handling](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/DisconnectHandler.swift): `Bluejay/Bluejay/DisconnectHandler.swift`
- [Background restoration](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/BackgroundRestorer.swift): `Bluejay/Bluejay/BackgroundRestorer.swift`
- [Logging observers](https://github.com/steamclock/bluejay/blob/master/Bluejay/Bluejay/LogObserver.swift): `Bluejay/Bluejay/LogObserver.swift`

### Heart sensor demos

- [Heart sensor client](https://github.com/steamclock/bluejay/blob/master/Bluejay/BluejayHeartSensorDemo/ScanViewController.swift): `Bluejay/BluejayHeartSensorDemo/ScanViewController.swift`
- [Sensor interaction UI](https://github.com/steamclock/bluejay/blob/master/Bluejay/BluejayHeartSensorDemo/SensorViewController.swift): `Bluejay/BluejayHeartSensorDemo/SensorViewController.swift`
- [Virtual BLE sensor](https://github.com/steamclock/bluejay/blob/master/Bluejay/DittojayHeartSensorDemo/DittojayViewController.swift): `Bluejay/DittojayHeartSensorDemo/DittojayViewController.swift`
- [Heart-rate data](https://github.com/steamclock/bluejay/blob/master/Bluejay/DittojayHeartSensorDemo/HeartRateMeasurement.swift): `Bluejay/DittojayHeartSensorDemo/HeartRateMeasurement.swift`

### Other components

- **Calling app**
- **CoreBluetooth**

## Connections

- Calling app → Bluejay API: calls API
- Bluejay API → Peripheral scanning: starts scan
- Peripheral scanning → CoreBluetooth: scans for
- Peripheral scanning → Calling app: returns discoveries
- Bluejay API → Connection management: connects or disconnects
- Connection management → CoreBluetooth: manages connection
- Connection management → FIFO operation queue: schedules operations
- FIFO operation queue → Service discovery: runs operations
- FIFO operation queue → Characteristic reads: runs operations
- FIFO operation queue → Characteristic writes: runs operations
- FIFO operation queue → Characteristic listening: runs operations
- Service discovery → CoreBluetooth: discovers services
- Characteristic reads → CoreBluetooth: reads characteristic
- Characteristic writes → CoreBluetooth: writes characteristic
- Characteristic listening → CoreBluetooth: subscribes to updates
- Data serialization → Characteristic reads: decodes data
- Data serialization → Characteristic writes: encodes data
- Bluejay API → Connection observers: notifies events
- Bluejay API → Disconnect handling: notifies disconnection
- Bluejay API → Background restoration: supports restoration
- Bluejay API → Logging observers: emits logs
- Heart sensor client → Bluejay API: scans and connects
- Sensor interaction UI → Bluejay API: reads and listens
- Sensor interaction UI → Connection observers: registers observers
- Virtual BLE sensor → CoreBluetooth: advertises services
- Virtual BLE sensor → Heart-rate data: creates measurements
- Virtual BLE sensor → CoreBluetooth: publishes updates