# pureswift/bluetooth architecture

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

- Interactive diagram: https://gitdiagram.com/pureswift/bluetooth
- Repository: https://github.com/pureswift/bluetooth

## Overview

##### Project Type and Purpose
- This is a Swift Package Manager library (“Bluetooth”) providing a multi‐layer implementation of Bluetooth SIG protocols (HCI, L2CAP, GAP, GATT) and utilities (UUIDs, metadata, code‐generation).
- It is a foundation library on which platform‐specific adapters depend (e.g., CoreBluetooth, BlueZ, Web API).

##### File Structure Analysis
- Top‐level:
- Configuration: .devcontainer, .github/workflows, swiftlint, swift-format.
- Package.swift: SPM manifest defining library targets.
- Assets, LICENSE, README.md.
- Plugins/GenerateBluetoothDefinitions: A Swift‐based code‐generation plugin for Bluetooth identifiers.
- Sources/: Each subfolder is an independent Swift target/module:
- Bluetooth: Core types (Address, UUID, Data), Streams, Extensions.
- BluetoothGAP: Generic Access Profile (advertising, scanning).
- BluetoothGATT: Generic Attribute Profile (services, characteristics, client/server logic).
- BluetoothHCI: Host‐Controller Interface (commands, events, low‐energy primitives).
- BluetoothMacros, BluetoothMetadata: Compile‐time helpers and JSON‐based metadata resources.
- GenerateBluetooth: A command‐line tool for code generation (alternative path to Plugins).
- Tests/: Unit tests for each layer.

##### README Insights
- Describes core library use (import Bluetooth) and lists supported platforms via external adapter libraries.

##### Detailed Capturing
- Every SPM target as a distinct component.
- That BluetoothMacros and BluetoothMetadata support the main modules.
- “Package.swift” as orchestrating these modules.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration and CI/CD
    subgraph "Configuration"
        Package["Package.swift"]:::config
        CI["CI/CD Pipelines"]:::config
        Dev[".devcontainer"]:::config
        Lint[".swiftlint.yml"]:::config
        Format[".swift-format"]:::config
    end

    %% Core Modules
    subgraph "Swift Package Modules"
        Core["Bluetooth"]:::module
        HCI["BluetoothHCI"]:::module
        L2CAP["L2CAPSocket"]:::module
        GAP["BluetoothGAP"]:::module
        GATT["BluetoothGATT"]:::module
        Metadata["BluetoothMetadata"]:::metadata
        Macros["BluetoothMacros"]:::metadata
    end

    %% Plugins and Tools
    subgraph "Code Generation"
        Plugin["GenerateBluetoothDefinitions"]:::plugin
        Tool["GenerateBluetooth"]:::plugin
    end

    %% External Adapters
    subgraph "Platform Adapters"
        CB["CoreBluetooth"]:::external
        BZ["BlueZ"]:::external
        Android["Android JNI"]:::external
        Web["Web Bluetooth API"]:::external
        Embedded["Embedded Stacks (BTStack/NimBLE/Zephyr)"]:::external
    end

    %% Tests
    Tests["Bluetooth Tests"]:::test

    %% Application Boundary
    App["Application"]:::external

    %% Relationships
    Core -->|"invokes"| HCI
    HCI -->|"data/events"| GAP
    GAP -->|"data/events"| GATT
    GATT -->|"service/characteristic API"| App

    Metadata -.->|"provides JSON metadata"| Core
    Macros -.->|"compile-time helpers"| Core

    Plugin -.->|"generates Swift UUIDs"| Core
    Plugin -.->|"generates Swift UUIDs"| GAP
    Plugin -.->|"generates Swift UUIDs"| GATT
    Tool -.->|"command-line code gen"| Core
    Tool -.->|"command-line code gen"| GAP
    Tool -.->|"command-line code gen"| GATT

    CB -.->|"implements HCI interface"| HCI
    BZ -.->|"implements HCI interface"| HCI
    Android -.->|"implements HCI interface"| HCI
    Web -.->|"implements HCI interface"| HCI
    Embedded -.->|"implements HCI interface"| HCI

    Tests -->|"tests modules"| Core
    Tests -->|"tests modules"| HCI
    Tests -->|"tests modules"| GAP
    Tests -->|"tests modules"| GATT

    %% Click Events
    click Core "https://github.com/pureswift/bluetooth/tree/master/Sources/Bluetooth"
    click HCI "https://github.com/pureswift/bluetooth/tree/master/Sources/BluetoothHCI"
    click L2CAP "https://github.com/pureswift/bluetooth/blob/master/Sources/Bluetooth/L2CAPSocket.swift"
    click GAP "https://github.com/pureswift/bluetooth/tree/master/Sources/BluetoothGAP"
    click GATT "https://github.com/pureswift/bluetooth/tree/master/Sources/BluetoothGATT"
    click Metadata "https://github.com/pureswift/bluetooth/tree/master/Sources/BluetoothMetadata"
    click Macros "https://github.com/pureswift/bluetooth/tree/master/Sources/BluetoothMacros"
    click Plugin "https://github.com/pureswift/bluetooth/tree/master/Plugins/GenerateBluetoothDefinitions"
    click Tool "https://github.com/pureswift/bluetooth/tree/master/Sources/GenerateBluetooth"
    click Package "https://github.com/pureswift/bluetooth/blob/master/Package.swift"
    click CI "https://github.com/pureswift/bluetooth/tree/master/.github/workflows"
    click Dev "https://github.com/pureswift/bluetooth/blob/master/.devcontainer/devcontainer.json"
    click Lint "https://github.com/pureswift/bluetooth/blob/master/.swiftlint.yml"
    click Format "https://github.com/pureswift/bluetooth/blob/master/.swift-format"
    click Tests "https://github.com/pureswift/bluetooth/tree/master/Tests/BluetoothTests"

    %% Styles
    classDef module fill:#A6CEE3,stroke:#333,stroke-width:1px
    classDef metadata fill:#B2DF8A,stroke:#333,stroke-width:1px
    classDef plugin fill:#FDBF6F,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef config fill:#D9D9D9,stroke:#333,stroke-width:1px
    classDef test fill:#BBBBBB,stroke:#333,stroke-width:1px
```
