# kuleuven-cosic/whisperpair architecture

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

- Interactive diagram: https://gitdiagram.com/kuleuven-cosic/whisperpair
- Repository: https://github.com/kuleuven-cosic/whisperpair

## Overview

WhisperPair is a Fast Pair security-testing harness: an operator selects a nearby device, configures and runs protocol or pairing attacks, and reviews progress and results. The web UI controls a Linux/BlueZ server over the network. The server discovers and manages devices, performs Fast Pair operations, and uses RFCOMM for Audio Switch messaging; model metadata is resolved through Google’s service and cached locally. The graph reflects documented capabilities, but several UI routes and server handlers were not sampled, so those connections are omitted or marked unverified.

Main entry points: [`toolkit-server/src/index.ts`](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/index.ts) (HTTP and socket API), [`toolkit-server/src/fast-pair-service.ts`](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/fast-pair-service.ts) (Fast Pair operations), [`toolkit-server/src/device-manager.ts`](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/device-manager.ts) (Device manager), [`toolkit-server/src/message-stream/session.ts`](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/session.ts) (RFCOMM session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_ui_page["Device dashboard<br/>[page.tsx]"]
  node_ui_device["Device view<br/>[device.tsx]"]
  node_ui_attack["Attack controls<br/>[attack.tsx]"]
  node_ui_model["Set model ID<br/>[set-model-id.tsx]"]
  node_ui_task["Task status"]
  node_ui_details["Device details<br/>[device-details.tsx]"]
  node_ui_services["Service view<br/>[services.tsx]"]
  node_ui_primitives["UI primitives"]
end

subgraph group_api["Server control"]
  node_server["HTTP and socket API<br/>[index.ts]"]
  node_tasks["Task execution<br/>[task.ts]"]
end

subgraph group_bluetooth["Bluetooth and protocol"]
  node_device_manager["Device manager<br/>[device-manager.ts]"]
  node_device_map["Device lookup map<br/>[device-map.ts]"]
  node_fast_pair["Fast Pair operations"]
  node_protocol["Pairing protocol<br/>[protocol.ts]"]
  node_message_parser["RFCOMM parser<br/>[parser.ts]"]
  node_message_session["RFCOMM session<br/>[session.ts]"]
  node_rfcomm["RFCOMM transport<br/>[rfcomm.ts]"]
  node_bluetoothctl["Bluetooth control<br/>[bluetoothctl.ts]"]
end

subgraph group_metadata["Device metadata"]
  node_model_resolver["Model ID resolver<br/>[index.ts]"]
  node_cache[("Local metadata cache<br/>[cache.ts]")]
end

node_operator(("Researcher"))
node_google{{"Google device service"}}
node_target(("Bluetooth device"))

node_operator -->|"uses"| node_ui_page
node_ui_page -.->|"presents"| node_ui_device
node_ui_device -.->|"shows details"| node_ui_details
node_ui_device -->|"shows services"| node_ui_services
node_ui_page -.->|"offers testing"| node_ui_attack
node_ui_attack -.->|"requests attacks"| node_server
node_ui_model -.->|"sets model ID"| node_server
node_ui_task -->|"emits cancel"| node_server
node_ui_primitives -.->|"renders controls"| node_ui_attack
node_ui_primitives -->|"renders status"| node_ui_task
node_ui_primitives -->|"renders view"| node_ui_services
node_server -.->|"serves control data"| node_ui_page
node_server -->|"queries devices"| node_device_manager
node_server -->|"resolves model data"| node_model_resolver
node_server -.->|"runs tasks"| node_tasks
node_server -->|"forwards events"| node_device_manager
node_device_manager -->|"tracks devices"| node_device_map
node_device_manager -->|"creates service"| node_fast_pair
node_device_manager -.->|"discovers device"| node_target
node_fast_pair -->|"builds messages"| node_protocol
node_fast_pair -->|"fetches device data"| node_model_resolver
node_fast_pair -->|"uses session"| node_message_session
node_fast_pair -->|"controls pairing"| node_bluetoothctl
node_message_session -->|"opens channel"| node_rfcomm
node_message_session -->|"parses stream"| node_message_parser
node_message_session -->|"sends messages"| node_target
node_model_resolver -->|"reads and writes"| node_cache
node_model_resolver -->|"fetches metadata"| node_google
node_protocol -.->|"tests protocol"| node_target
node_fast_pair -->|"runs attacks"| node_target

click node_ui_page "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/app/page.tsx"
click node_ui_device "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/device.tsx"
click node_ui_attack "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/attack.tsx"
click node_ui_model "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/set-model-id.tsx"
click node_ui_task "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/task-controller.tsx"
click node_ui_details "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/device-details.tsx"
click node_ui_services "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/services.tsx"
click node_ui_primitives "https://github.com/kuleuven-cosic/whisperpair/tree/main/toolkit-ui/src/components/ui"
click node_server "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/index.ts"
click node_tasks "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/task.ts"
click node_device_manager "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/device-manager.ts"
click node_device_map "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/device-map.ts"
click node_fast_pair "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/fast-pair-service.ts"
click node_protocol "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/protocol.ts"
click node_message_parser "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/parser.ts"
click node_message_session "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/session.ts"
click node_rfcomm "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/rfcomm.ts"
click node_bluetoothctl "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/bluetoothctl.ts"
click node_model_resolver "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/model-id-resolver/index.ts"
click node_cache "https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/cache.ts"

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_ui_page,node_ui_device,node_ui_attack,node_ui_model,node_ui_task,node_ui_details,node_ui_services,node_ui_primitives toneBlue
class node_server,node_tasks toneAmber
class node_device_manager,node_device_map,node_fast_pair,node_protocol,node_message_parser,node_message_session,node_rfcomm,node_bluetoothctl toneMint
class node_model_resolver,node_cache toneRose
class node_operator,node_google,node_target toneIndigo
```

## Components

### Web interface

- [Device dashboard](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/app/page.tsx): `toolkit-ui/src/app/page.tsx`
- [Device view](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/device.tsx): `toolkit-ui/src/components/device.tsx`
- [Attack controls](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/attack.tsx): `toolkit-ui/src/components/attack.tsx`
- [Set model ID](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/set-model-id.tsx): `toolkit-ui/src/components/set-model-id.tsx`
- [Task status](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/task-controller.tsx): `toolkit-ui/src/components/task-controller.tsx`
- [Device details](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/device-details.tsx): `toolkit-ui/src/components/device-details.tsx`
- [Service view](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-ui/src/components/services.tsx): `toolkit-ui/src/components/services.tsx`
- [UI primitives](https://github.com/kuleuven-cosic/whisperpair/tree/main/toolkit-ui/src/components/ui): `toolkit-ui/src/components/ui`

### Server control

- [HTTP and socket API](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/index.ts): `toolkit-server/src/index.ts`
- [Task execution](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/task.ts): `toolkit-server/src/task.ts`

### Bluetooth and protocol

- [Device manager](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/device-manager.ts): `toolkit-server/src/device-manager.ts`
- [Device lookup map](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/device-map.ts): `toolkit-server/src/device-map.ts`
- [Fast Pair operations](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/fast-pair-service.ts): `toolkit-server/src/fast-pair-service.ts`
- [Pairing protocol](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/protocol.ts): `toolkit-server/src/protocol.ts`
- [RFCOMM parser](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/parser.ts): `toolkit-server/src/message-stream/parser.ts`
- [RFCOMM session](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/session.ts): `toolkit-server/src/message-stream/session.ts`
- [RFCOMM transport](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/message-stream/rfcomm.ts): `toolkit-server/src/message-stream/rfcomm.ts`
- [Bluetooth control](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/bluetoothctl.ts): `toolkit-server/src/bluetoothctl.ts`

### Device metadata

- [Model ID resolver](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/model-id-resolver/index.ts): `toolkit-server/src/model-id-resolver/index.ts`
- [Local metadata cache](https://github.com/kuleuven-cosic/whisperpair/blob/main/toolkit-server/src/cache.ts): `toolkit-server/src/cache.ts`

### Other components

- **Researcher**
- **Google device service**
- **Bluetooth device**

## Connections

- Researcher → Device dashboard: uses (evidence: `README.md`)
- Device dashboard → Device view: presents
- Device view → Device details: shows details
- Device view → Service view: shows services (evidence: `toolkit-ui/src/components/services.tsx`)
- Device dashboard → Attack controls: offers testing
- Attack controls → HTTP and socket API: requests attacks (evidence: `README.md`)
- Set model ID → HTTP and socket API: sets model ID
- Task status → HTTP and socket API: emits cancel (evidence: `toolkit-ui/src/components/task-controller.tsx`)
- UI primitives → Attack controls: renders controls (evidence: `toolkit-ui/src/components/attack.tsx`)
- UI primitives → Task status: renders status (evidence: `toolkit-ui/src/components/task-controller.tsx`)
- UI primitives → Service view: renders view (evidence: `toolkit-ui/src/components/services.tsx`)
- HTTP and socket API → Device dashboard: serves control data (evidence: `README.md`)
- HTTP and socket API → Device manager: queries devices (evidence: `toolkit-server/src/index.ts`)
- HTTP and socket API → Model ID resolver: resolves model data (evidence: `toolkit-server/src/index.ts`)
- HTTP and socket API → Task execution: runs tasks (evidence: `toolkit-server/src/index.ts`)
- HTTP and socket API → Device manager: forwards events (evidence: `toolkit-server/src/index.ts`)
- Device manager → Device lookup map: tracks devices (evidence: `toolkit-server/src/device-manager.ts`)
- Device manager → Fast Pair operations: creates service (evidence: `toolkit-server/src/device-manager.ts`)
- Device manager → Bluetooth device: discovers device (evidence: `README.md`)
- Fast Pair operations → Pairing protocol: builds messages (evidence: `toolkit-server/src/fast-pair-service.ts`)
- Fast Pair operations → Model ID resolver: fetches device data (evidence: `toolkit-server/src/fast-pair-service.ts`)
- Fast Pair operations → RFCOMM session: uses session (evidence: `toolkit-server/src/fast-pair-service.ts`)
- Fast Pair operations → Bluetooth control: controls pairing (evidence: `toolkit-server/src/fast-pair-service.ts`)
- RFCOMM session → RFCOMM transport: opens channel (evidence: `toolkit-server/src/message-stream/session.ts`)
- RFCOMM session → RFCOMM parser: parses stream (evidence: `toolkit-server/src/message-stream/session.ts`)
- RFCOMM session → Bluetooth device: sends messages (evidence: `toolkit-server/src/message-stream/session.ts`)
- Model ID resolver → Local metadata cache: reads and writes (evidence: `toolkit-server/src/model-id-resolver/index.ts`)
- Model ID resolver → Google device service: fetches metadata (evidence: `toolkit-server/src/model-id-resolver/index.ts`)
- Pairing protocol → Bluetooth device: tests protocol (evidence: `README.md`)
- Fast Pair operations → Bluetooth device: runs attacks (evidence: `README.md`)
