# tarlogicsecurity/bluespy architecture

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

- Interactive diagram: https://gitdiagram.com/tarlogicsecurity/bluespy
- Repository: https://github.com/tarlogicsecurity/bluespy

## Overview

BlueSpy is a Bluetooth-audio recording and playback proof of concept. Its main workflow accepts a target address, attempts pairing, connects, records audio to a file, and optionally plays it back. The README also documents separate pairing, connection, and recording entry points. The sampled source shows the orchestration and command execution; the README identifies the external tools and runtime requirements.

Main entry points: [`BlueSpy.py`](https://github.com/tarlogicsecurity/bluespy/blob/main/BlueSpy.py) (CLI workflow), [`core.py`](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py) (Record audio), [`system.py`](https://github.com/tarlogicsecurity/bluespy/blob/main/system.py) (Command runner), [`interface.py`](https://github.com/tarlogicsecurity/bluespy/blob/main/interface.py) (Text interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow"]
  node_main["CLI workflow<br/>[BlueSpy.py]"]
end

subgraph group_bluetooth["Bluetooth"]
  node_pair["Pair target<br/>[core.py]"]
  node_connect["Connect target<br/>[core.py]"]
  node_address["Address helpers<br/>[core.py]"]
  node_bluez["BlueZ tools"]
end

subgraph group_audio["Audio"]
  node_record["Record audio<br/>[core.py]"]
  node_playback["Play recording<br/>[core.py]"]
  node_pulse["PulseAudio tools"]
  node_recording["Audio file"]
end

subgraph group_support["Support"]
  node_interface["Text interface<br/>[interface.py]"]
  node_runner["Command runner<br/>[system.py]"]
end

node_user(("Operator"))
node_target(("Bluetooth device"))

node_user -->|"runs"| node_main
node_main -->|"pairs"| node_pair
node_main -->|"connects"| node_connect
node_main -->|"records"| node_record
node_main -->|"optionally plays"| node_playback
node_main -->|"prompts and logs"| node_interface
node_pair -->|"executes commands"| node_runner
node_connect -->|"executes commands"| node_runner
node_record -->|"executes commands"| node_runner
node_playback -->|"executes command"| node_runner
node_pair -->|"uses btmgmt"| node_bluez
node_connect -->|"uses bluetoothctl"| node_bluez
node_record -->|"derives device names"| node_address
node_record -->|"selects profile and captures"| node_pulse
node_playback -->|"uses paplay"| node_pulse
node_record -->|"writes"| node_recording
node_playback -->|"reads"| node_recording
node_pair -.->|"pairs with"| node_target
node_connect -.->|"connects to"| node_target

click node_main "https://github.com/tarlogicsecurity/bluespy/blob/main/BlueSpy.py"
click node_interface "https://github.com/tarlogicsecurity/bluespy/blob/main/interface.py"
click node_pair "https://github.com/tarlogicsecurity/bluespy/blob/main/core.py"
click node_connect "https://github.com/tarlogicsecurity/bluespy/blob/main/core.py"
click node_address "https://github.com/tarlogicsecurity/bluespy/blob/main/core.py"
click node_record "https://github.com/tarlogicsecurity/bluespy/blob/main/core.py"
click node_playback "https://github.com/tarlogicsecurity/bluespy/blob/main/core.py"
click node_runner "https://github.com/tarlogicsecurity/bluespy/blob/main/system.py"

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_main toneBlue
class node_pair,node_connect,node_address,node_bluez toneAmber
class node_record,node_playback,node_pulse,node_recording toneMint
class node_interface,node_runner toneRose
class node_user,node_target toneIndigo
```

## Components

### Workflow

- [CLI workflow](https://github.com/tarlogicsecurity/bluespy/blob/main/BlueSpy.py): `BlueSpy.py`

### Bluetooth

- [Pair target](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py): `core.py`
- [Connect target](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py): `core.py`
- [Address helpers](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py): `core.py`
- **BlueZ tools**

### Audio

- [Record audio](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py): `core.py`
- [Play recording](https://github.com/tarlogicsecurity/bluespy/blob/main/core.py): `core.py`
- **PulseAudio tools**
- **Audio file**

### Support

- [Text interface](https://github.com/tarlogicsecurity/bluespy/blob/main/interface.py): `interface.py`
- [Command runner](https://github.com/tarlogicsecurity/bluespy/blob/main/system.py): `system.py`

### Other components

- **Operator**
- **Bluetooth device**

## Connections

- Operator → CLI workflow: runs (evidence: `README.md`)
- CLI workflow → Pair target: pairs (evidence: `BlueSpy.py`)
- CLI workflow → Connect target: connects (evidence: `BlueSpy.py`)
- CLI workflow → Record audio: records (evidence: `BlueSpy.py`)
- CLI workflow → Play recording: optionally plays (evidence: `BlueSpy.py`)
- CLI workflow → Text interface: prompts and logs (evidence: `BlueSpy.py`)
- Pair target → Command runner: executes commands (evidence: `core.py`)
- Connect target → Command runner: executes commands (evidence: `core.py`)
- Record audio → Command runner: executes commands (evidence: `core.py`)
- Play recording → Command runner: executes command (evidence: `core.py`)
- Pair target → BlueZ tools: uses btmgmt (evidence: `core.py`)
- Connect target → BlueZ tools: uses bluetoothctl (evidence: `core.py`)
- Record audio → Address helpers: derives device names (evidence: `core.py`)
- Record audio → PulseAudio tools: selects profile and captures (evidence: `core.py`)
- Play recording → PulseAudio tools: uses paplay (evidence: `core.py`)
- Record audio → Audio file: writes (evidence: `README.md`)
- Play recording → Audio file: reads (evidence: `README.md`)
- Pair target → Bluetooth device: pairs with
- Connect target → Bluetooth device: connects to
