# pythops/bluetui architecture

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

- Interactive diagram: https://gitdiagram.com/pythops/bluetui
- Repository: https://github.com/pythops/bluetui

## Overview

##### Project type and purpose
- bluetui is a single-binary, terminal user interface (TUI) application written in Rust for managing Bluetooth adapters and devices on Linux.
- It interacts with the OS’s BlueZ stack (via D-Bus) and the rfkill kernel interface to scan, pair, trust, and connect/disconnect devices.

##### File structure
- Top-level Rust project (Cargo.toml, src/)
- src/cli.rs         – parses command-line flags (e.g. custom config path)
- src/config.rs      – loads and validates TOML configuration from $HOME/.config/bluetui/config.toml
- src/bluetooth.rs   – wraps BlueZ D-Bus calls for scan, pair, connect, etc.
- src/rfkill.rs      – interfaces with rfkill to toggle adapter power/discovery
- src/event.rs       – defines events for user input, BlueZ callbacks, rfkill notifications
- src/handler.rs     – dispatches events to action functions in bluetooth.rs and rfkill.rs
- src/app.rs         – wires together CLI, config, event loop, handlers, UI and notifications
- src/ui.rs          – high-level layout of TUI sections (Adapters, Paired, New devices)
- src/tui.rs         – lower-level terminal-drawing engine (based on tui-rs crate)
- src/notification.rs– triggers desktop notifications via libnotify or similar
- src/spinner.rs     – manages “scanning” spinner animations
- src/confirmation.rs– pop-up dialog for rename, unpair confirmation
- src/main.rs        – entry point: calls app::run()

##### README
- Confirms dependencies: BlueZ, optional nerdfonts
- Describes keybindings and features (scan, pair, trust, power toggle)

##### Components & interactions
1. CLI Parser
2. Config Loader
3. Event Loop & Dispatcher
4. Bluetooth Controller (BlueZ D-Bus)
5. RFKill Controller (kernel rfkill)
6. TUI Renderer (tui-rs)
7. UI Widgets / Dialogs
8. Notification Service (libnotify)
9. Spinner Manager
10. Confirmation Dialog
- CLI Parser → Config Loader (passes config path)
- Config Loader → App Core (supplies user settings)
- App Core ↔ Event Loop (registers input sources and handlers)
- Event Loop → Bluetooth Controller (on “scan”, “pair”, “connect”)
- Event Loop → RFKill Controller (on “power on/off”, “discovery toggle”)
- Bluetooth Controller → Event Loop (on device found/paired state changes)
- RFKill Controller → Event Loop (on adapter state change)
- Event Loop → UI Widgets (triggers UI state update)
- Event Loop → Notification Service (e.g. “device connected”)
- Spinner Manager → TUI Renderer (updates spinner)
- Confirmation Dialog ↔ Event Loop (captures user confirmation)
c. Architectural patterns & design principles
- MVC-style separation:
- Model = current Bluetooth/rfkill state maintained by App Core
- View = TUI Renderer + UI Widgets
- Controller = Event Loop + Handlers
- Event-driven loop for decoupling I/O from business logic
- Single responsibility per module (config, CLI, UI, notifications)
d. Key technologies & libraries
- Rust & Cargo for build
- BlueZ D-Bus API (via dbus-crate or zbus)
- rfkill subsystem (via ioctl or sysfs)
- tui-rs crate for terminal UI
- clap or structopt for CLI parsing
- toml for config parsing
- libnotify or notify-rust for desktop notifications

##### Detail is critical
- Of the src/*.rs modules as components.
- D-Bus and kernel interfaces externally.
- Event loop as the heart of the MVC pattern.
- Avoid over-simplification by including config loading, CLI parsing, and notifications as first-class parts of the system.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Entry Point"
        Main["Entry Point\nsrc/main.rs"]:::input
    end

    subgraph "Input Layer"
        CLI["CLI Parser\nsrc/cli.rs"]:::input
    end

    subgraph "Core Layer"
        ConfigFile(("Config File\n~/.config/bluetui/config.toml")):::config
        Config["Config Loader\nsrc/config.rs"]:::core
        App["App Core\nsrc/app.rs"]:::core
        Event["Event Loop\nsrc/event.rs"]:::core
        Handler["Event Dispatcher\nsrc/handler.rs"]:::core
    end

    subgraph "Integration Layer"
        BT["Bluetooth Controller\nsrc/bluetooth.rs"]:::integration
        RF["RFKill Controller\nsrc/rfkill.rs"]:::integration
    end

    subgraph "Presentation Layer"
        UIW["UI Widgets\nsrc/ui.rs"]:::presentation
        TUI["TUI Renderer\nsrc/tui.rs"]:::presentation
        Spinner["Spinner Manager\nsrc/spinner.rs"]:::presentation
        Confirm["Confirmation Dialog\nsrc/confirmation.rs"]:::presentation
    end

    subgraph "Notification Layer"
        Notif["Notification Service\nsrc/notification.rs"]:::notification
    end

    DBus(("BlueZ D-Bus Service")):::external
    KernelIF(("Kernel rfkill Interface")):::external
    NotifyD(("Notification Daemon")):::external

    Main -->|initializes| App
    CLI -->|passes config path| Config
    ConfigFile -->|loads TOML| Config
    Config -->|supplies settings| App
    App -->|registers| Event
    App -->|registers| Handler
    App -->|wires| UIW
    App -->|wires| Notif

    Event -->|dispatch event| Handler
    Handler -->|calls| BT
    Handler -->|calls| RF
    BT -->|signals state change| Event
    RF -->|signals state change| Event
    Event -->|triggers UI update| UIW
    UIW -->|draw calls| TUI
    Spinner -->|updates spinner| TUI
    Event -->|"device connected"| Notif

    Confirm -->|requests| Event
    Event -->|shows dialog| Confirm

    BT -->|dbus call| DBus
    RF -->|ioctl/sysfs| KernelIF
    Notif -->|desktop notify| NotifyD

    classDef input fill:#e0f7fa,stroke:#000
    classDef core fill:#e8f5e9,stroke:#000
    classDef integration fill:#fff3e0,stroke:#000
    classDef presentation fill:#fffde7,stroke:#000
    classDef notification fill:#fce4ec,stroke:#000
    classDef external fill:#eceff1,stroke:#000,stroke-dasharray: 5 5
    classDef config fill:#e0e0e0,stroke:#000,stroke-dasharray: 2 2

    click CLI "https://github.com/pythops/bluetui/blob/master/src/cli.rs"
    click Config "https://github.com/pythops/bluetui/blob/master/src/config.rs"
    click Event "https://github.com/pythops/bluetui/blob/master/src/event.rs"
    click Handler "https://github.com/pythops/bluetui/blob/master/src/handler.rs"
    click App "https://github.com/pythops/bluetui/blob/master/src/app.rs"
    click Main "https://github.com/pythops/bluetui/blob/master/src/main.rs"
    click BT "https://github.com/pythops/bluetui/blob/master/src/bluetooth.rs"
    click RF "https://github.com/pythops/bluetui/blob/master/src/rfkill.rs"
    click TUI "https://github.com/pythops/bluetui/blob/master/src/tui.rs"
    click UIW "https://github.com/pythops/bluetui/blob/master/src/ui.rs"
    click Notif "https://github.com/pythops/bluetui/blob/master/src/notification.rs"
    click Spinner "https://github.com/pythops/bluetui/blob/master/src/spinner.rs"
    click Confirm "https://github.com/pythops/bluetui/blob/master/src/confirmation.rs"
```
