# timfish/usb_enumeration architecture

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

- Interactive diagram: https://gitdiagram.com/timfish/usb_enumeration
- Repository: https://github.com/timfish/usb_enumeration

## Overview

##### Project type and purpose
- usb_enumeration is an open-source, cross-platform Rust library (crate) whose sole responsibility is to enumerate USB devices on the host system and provide an event subscription interface.
- It is not a web service or a full-stack application, but rather a systems-level library that abstracts OS-specific USB enumeration APIs under one uniform Rust API.

##### File structure
- Cargo.toml, .rustfmt.toml, and .github/ workflows: standard Rust crate metadata, formatting, and CI.
- src/lib.rs: the public API surface (functions like `enumerate` and the `Observer` type).
- src/common.rs: shared types and utilities (e.g. `UsbDevice` struct, `Event` enum, channel setup).
- src/linux.rs, src/macos.rs, src/windows.rs: platform-specific implementations that call into each OS’s USB enumeration subsystem.
- No database, no networking, no front-end: everything lives in the library and the host OS.

##### README for additional insights
- Public API:
- enumerate(None, None) → returns Vec<UsbDevice>
- Observer → subscribe to change events on a background thread, communicates over an mpsc channel
- Internally, the Observer likely spins up a polling loop (with configurable interval) that invokes the same platform enumerator and diffs results to emit Initial, Connect, Disconnect events.

a. Main components:
- Consumer (the user’s Rust application code)
- usb_enumeration crate
– Public API layer (`lib.rs`)
– Shared domain (`common.rs` – `UsbDevice`, `Event`, channel)
– Platform adapters (`linux.rs`, `macos.rs`, `windows.rs`)
– Observer subsystem (background thread + mpsc channel)
- Underlying OS USB subsystem / system calls (WinAPI SetupDi*, libusb on Linux, IOKit on macOS)
b. Relationships and interactions:
1. Consumer calls `usb_enumeration::enumerate()` or constructs an `Observer`.
2. The Public API dispatches at compile time (via #[cfg]) to the proper platform adapter.
3. Platform adapter invokes native OS APIs to gather USB device info.
4. Data flows back as Vec<UsbDevice> or as Event messages over a channel.
5. The Observer component spawns a thread, on each tick it calls the same adapter, diffs the results, and sends `Event::Connect/Disconnect/Initial` through the channel to the Consumer.
c. Architectural patterns / design principles:
– Adapter pattern: each OS gets its own adapter module behind a uniform trait or API.
– Single responsibility: `common.rs` for data types, adapters for OS specifics, `lib.rs` for API orchestration.
– Observer pattern for event subscription, implemented via Rust channels and a background thread.
d. Relevant technologies:
– Rust standard library threads and channels (std::sync::mpsc or crossbeam)
– Conditional compilation (`#[cfg(target_os = "...")]`)
– OS-specific APIs: WinAPI SetupDi*, libusb or direct syscalls on Linux, IOKit on macOS

##### Detail without overthinking
- Compile-time dispatch to the appropriate adapter.
- Observer’s polling loop and channel.
- Keep it simple: the goal is to leave no piece of the library architecture undocumented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Consumer["Consumer Application"]:::consumer

    subgraph "USB Enumeration Library"
        direction TB
        Cargo["Crate Manifest & Metadata\n(Cargo.toml)"]:::config
        API["Public API Layer\n(lib.rs)"]:::internals
        Common["Shared Domain Types\n(common.rs)"]:::internals
        subgraph "Platform Adapters"
            direction TB
            Linux["Linux Adapter\n(linux.rs)"]:::adapter
            Mac["macOS Adapter\n(macos.rs)"]:::adapter
            Win["Windows Adapter\n(windows.rs)"]:::adapter
        end
        Observer["Observer Subsystem\n(lib.rs)"]:::observer
    end

    OS["OS USB Subsystem"]:::external
    Channel["MPSC Channel"]:::internal

    %% Call flows
    Consumer -->|"enumerate() / subscribe()"| API
    API --> Common

    API -->|"compile-time dispatch\nenumerate()"| Linux
    API -->|"compile-time dispatch\nenumerate()"| Mac
    API -->|"compile-time dispatch\nenumerate()"| Win

    Linux -->|"calls native APIs"| OS
    Mac -->|"calls native APIs"| OS
    Win -->|"calls native APIs"| OS

    OS -->|"Vec<UsbDevice>"| API
    API -->|"<<Vec<UsbDevice>>"| Consumer

    %% Observer flows
    API -->|"spawn Observer"| Observer
    Observer -->|"poll & enumerate()"| Linux
    Observer -->|"poll & enumerate()"| Mac
    Observer -->|"poll & enumerate()"| Win
    OS -->|"Vec<UsbDevice>"| Observer
    Observer -->|"diff_and_emit()"| Channel
    Channel -->|"Event Stream"| Consumer

    %% Click Events
    click API "https://github.com/timfish/usb_enumeration/blob/master/src/lib.rs"
    click Observer "https://github.com/timfish/usb_enumeration/blob/master/src/lib.rs"
    click Common "https://github.com/timfish/usb_enumeration/blob/master/src/common.rs"
    click Linux "https://github.com/timfish/usb_enumeration/blob/master/src/linux.rs"
    click Mac "https://github.com/timfish/usb_enumeration/blob/master/src/macos.rs"
    click Win "https://github.com/timfish/usb_enumeration/blob/master/src/windows.rs"
    click Cargo "https://github.com/timfish/usb_enumeration/blob/master/Cargo.toml"

    %% Styles
    classDef consumer fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef internals fill:#D4EFDF,stroke:#196F3D,color:#145A32;
    classDef adapter fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef observer fill:#FADBD8,stroke:#7B241C,color:#641E16;
    classDef external fill:#E5E7E9,stroke:#566573,color:#2C3E50;
    classDef config fill:#E8F8F5,stroke:#148F77,color:#0B5345;
    classDef internal fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
```
