# chhabraadhruv/buzzpair architecture

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

- Interactive diagram: https://gitdiagram.com/chhabraadhruv/buzzpair
- Repository: https://github.com/chhabraadhruv/buzzpair

## Overview

##### Project Type and Purpose
- Native macOS menu-bar application (built in Swift/SwiftUI within Xcode)
- Purpose: Discover Google Fast Pair BLE devices, manage connections, control ANC/volume/EQ, display battery levels, send system notifications.

##### File Structure
- Top-level files:
– README.md – project overview
- Implicit Xcode project (BuzzPair.xcodeproj) containing Swift source code:
– SwiftUI Views (UI)
– ViewModels (Combine)
– Services/Managers (Bluetooth scanning, pairing, audio control, notifications)
– Resources (assets, Info.plist, entitlements)

##### Extract Key Architecture from the README
- Features imply these core subsystems:
– Device Discovery & Pairing (Google Fast Pair protocol over BLE)
– Audio Controls (ANC modes, volume, EQ)
– Battery Monitoring (BLE characteristics)
– Menu-Bar Integration & UI (SwiftUI)
– Notifications (UserNotifications framework)

##### Main Components and Boundaries
a. Presentation Layer
– MenuBarController + SwiftUI Views
– ViewModels (expose device list, connection state, control commands)
b. Domain & Business Logic
– FastPairManager (implements Google Fast Pair handshake & GATT profiles)
– AudioControlManager (sets ANC/Transparency/Off modes)
– BatteryMonitor (reads and publishes battery level updates)
– SettingsManager (persists user preferences)
c. Infrastructure Layer
– CoreBluetooth Framework (BLE scanning, GATT operations)
– UserNotifications Framework (system-level alerts)
– AVFoundation/System Audio APIs (volume, EQ)
– Local Storage (UserDefaults or on-disk plist for preferences)
d. External Services
– Google Fast Pair Service on the device (BLE GATT server)

##### Component Interactions
- On launch: MenuBarController initializes FastPairManager & BatteryMonitor
- FastPairManager scans via CoreBluetooth → detects BLE advertisement → performs pairing → notifies ViewModel
- ViewModel updates SwiftUI Views → user triggers ANC/volume/EQ commands → routed to AudioControlManager → invokes AVFoundation
- BatteryMonitor polls GATT characteristic via CoreBluetooth → updates ViewModel → UI updates battery gauge
- Notification triggers on “device found” → SettingsManager checks user prefs → UserNotifications delivers alert

##### Architectural Patterns & Principles
- MVVM pattern with SwiftUI + Combine
- Separation of Concerns: UI, Domain Logic, Infrastructure
- Dependency Injection: inject CoreBluetooth and UserNotifications services into managers
- Observer/Publish-Subscribe (Combine) for state propagation
- Clean layering to facilitate unit testing of managers without UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        MBC["MenuBarController"]:::ui
        SV["SwiftUI Views"]:::ui
        VM["ViewModels"]:::ui
    end

    %% Domain & Business Logic
    subgraph "Domain Logic"
        direction TB
        FPM["FastPairManager"]:::domain
        ACM["AudioControlManager"]:::domain
        BM["BatteryMonitor"]:::domain
        SM["SettingsManager"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        CB["CoreBluetooth Framework"]:::infra
        UN["UserNotifications Framework"]:::infra
        AV["AVFoundation / System Audio APIs"]:::infra
        LS[("LocalStorage (UserDefaults)")]:::infra
    end

    %% External Services
    subgraph "External"
        direction TB
        GPD["Google Fast Pair BLE Device"]:::external
    end

    %% File Structure
    subgraph "Project Files"
        direction TB
        README["Project Overview (README)"]:::doc
        ASSETS["Application Assets"]:::doc
    end

    %% Interactions
    MBC -->|"initialize()"| FPM
    MBC -->|"initialize()"| BM
    SV <-->|"bindsTo"| VM
    VM -->|"scanForDevices()"| FPM
    FPM -->|"use()"| CB
    CB -->|"detectAdvert()"| GPD
    FPM -->|"connect()"| GPD
    FPM -->|"notify() (Combine)"| VM
    VM -->|"triggerANC()/volume()/EQ()"| ACM
    ACM -->|"invoke()"| AV
    BM -->|"readBattery()"| CB
    CB -->|"batteryCharacteristic"| BM
    BM -->|"publish() (Combine)"| VM
    VM -->|"updateUI"| SV
    VM -->|"deviceFound"| SM
    SM -->|"checkPrefs()"| LS
    SM -->|"deliverAlert()"| UN
    UN -->|"notifyUser"| SV

    %% Click Events
    click README "https://github.com/chhabraadhruv/buzzpair/blob/main/README.md"
    click ASSETS "https://github.com/chhabraadhruv/buzzpair/tree/main/assets/"

    %% Styles
    classDef ui fill:#a8f0c6,stroke:#006400,color:#000;
    classDef domain fill:#c6dbf0,stroke:#004080,color:#000;
    classDef infra fill:#e0e0e0,stroke:#808080,color:#000;
    classDef external fill:#ffe0b2,stroke:#ff8000,color:#000;
    classDef doc fill:#f0f0f0,stroke:#999999,color:#000;
```
