# android/connectivity-samples architecture

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

- Interactive diagram: https://gitdiagram.com/android/connectivity-samples
- Repository: https://github.com/android/connectivity-samples

## Overview

##### Project type and purpose
- UwbRanging is an Android sample app demonstrating Ultra-Wideband (UWB) ranging.
- It comprises two Gradle modules:
- app – the Android application, UI, ViewModels, settings.
- uwbranging – a Kotlin library providing UWB session management via Google’s Nearby Connections.

##### File structure
- Top-level modules:
- uwbranging/… – core library with connectors (NearbyConnections, OOB), UwbConnectionManager, session scope, proto definitions, tests.
- app/… – Android app with HelloUwbApplication, AppContainer (dependency-injection), SettingsStore (Proto DataStore), UwbRangingControlSource, UI code under ui/, individual screens & ViewModels.
- Notice MVVM pattern in app and a repository-style control-source interface.
- Proto files: appsettings.proto (app settings) and uwbinfo.proto (UWB session info).

##### Main components
A. Android App (module: app)
- UI Layer
– HelloUwbApp.kt (Compose host)
– Screen composables under ui/home, ui/control, ui/send, ui/settings, ui/ranging.
- ViewModel Layer
– HomeViewModel, ControlViewModel, SendViewModel, SettingsViewModel, RangingViewModel.
- AppContainer (dependency injection)
– Provides instances of SettingsStore, UwbRangingControlSource, UwbRangingControlSourceImpl.
- Data Layer
– SettingsStore (Proto DataStore) → persists user settings.
– UwbRangingControlSource interface → abstract control API.
– UwbRangingControlSourceImpl → delegates to UwbConnectionManager in uwbranging module.

B. UWB Library (module: uwbranging)
- UwbConnectionManager (session orchestration)
- UwbEndpoint, EndpointEvents, UwbSessionScope (lifecycle)
- Impl sub-package:
– NearbyConnections & connectors (NearbyConnector, NearbyControllerConnector, NearbyControleeConnector, OobConnector).
– UwbConnectionManagerImpl, UwbOobEvent, UwbSessionScopeImpl
- Proto definitions (uwbinfo.proto) describing messages sent over Nearby Connections.

C. External Dependencies
- Google Nearby Connections API
- Android UWB hardware & platform APIs
- Proto DataStore (Jetpack DataStore)
- Jetpack Compose UI toolkit

##### Relationships and data flow
- UI → ViewModel: user events, callbacks (Compose calls).
- ViewModel → AppContainer: obtains control-source & settings store.
- ViewModel → SettingsStore: read/write settings.
- ViewModel → UwbRangingControlSource API: start/stop ranging, send data.
- UwbRangingControlSourceImpl → UwbConnectionManager (library): orchestrates NearbyConnections sessions.
- UwbConnectionManager → connectors → Google Nearby Connections → UWB radio transport.
- NearbyConnections → data arrives → UwbConnectionManager → callbacks → UI layer via Flow/LiveData.

##### Architectural patterns and principles
- MVVM – clear separation of UI (Compose) and business logic (ViewModels).
- Dependency injection via AppContainer.
- Repository/Control-Source pattern – exposes a simple interface to the UI.
- Modularization – decoupling app-specific UI from core UWB library.
- Proto DataStore – type-safe settings persistence.

##### Putting it all together
- Settings flow: SettingsStore ↔ Proto DataStore.
- Message formats (appsettings.proto, uwbinfo.proto).

## Diagram (Mermaid)

```mermaid
graph TB
    %% App Module
    subgraph "App Module" 
        direction TB
        subgraph "UI Layer"
            direction TB
            HelloUwbApp["HelloUwbApp"]:::ui
            MainActivity["MainActivity"]:::ui
            AppNavGraph["AppNavGraph"]:::ui
        end
        subgraph "ViewModel Layer"
            direction TB
            HomeVM["HomeViewModel"]:::vm
            ControlVM["ControlViewModel"]:::vm
            SendVM["SendViewModel"]:::vm
            SettingsVM["SettingsViewModel"]:::vm
            RangingVM["RangingViewModel"]:::vm
        end
        subgraph "Data Layer"
            direction TB
            AppContainer["AppContainer"]:::data
            AppContainerImpl["AppContainerImpl"]:::data
            SettingsStore["SettingsStore"]:::data
            SettingsStoreImpl["SettingsStoreImpl"]:::data
            ControlSource["UwbRangingControlSource"]:::data
            ControlSourceImpl["UwbRangingControlSourceImpl"]:::data
        end
    end

    %% UWB Library Module
    subgraph "uwbranging Library Module"
        direction TB
        subgraph "Core API"
            direction TB
            UwbConnMgr["UwbConnectionManager"]:::lib
            UwbEndpoint["UwbEndpoint"]:::lib
            EndpointEvents["EndpointEvents"]:::lib
            UwbSessionScope["UwbSessionScope"]:::lib
        end
        subgraph "Implementation"
            direction TB
            NearbyConn["NearbyConnections"]:::lib
            NearbyConnector["NearbyConnector"]:::lib
            NearbyCtrlConnector["NearbyControllerConnector"]:::lib
            NearbyControleeConnector["NearbyControleeConnector"]:::lib
            OobConnector["OobConnector"]:::lib
            UwbConnMgrImpl["UwbConnectionManagerImpl"]:::lib
            UwbOobEvent["UwbOobEvent"]:::lib
            UwbSessionScopeImpl["UwbSessionScopeImpl"]:::lib
        end
        UwbConnMgr -->|uses| NearbyConn
        UwbConnMgr -->|uses| NearbyConnector
        UwbConnMgr -->|uses| NearbyCtrlConnector
        UwbConnMgr -->|uses| NearbyControleeConnector
        UwbConnMgr -->|uses| OobConnector
        UwbConnMgrImpl -->|implements| UwbConnMgr
        UwbSessionScopeImpl -->|implements| UwbSessionScope
        NearbyConn -->|emits| UwbOobEvent
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        GoogleNearby["Google Nearby Connections API"]:::external
        AndroidUWB["Android UWB Hardware & APIs"]:::external
        ProtoDataStore["Proto DataStore"]:::external
        Compose["Jetpack Compose"]:::external
    end

    %% Interactions
    HelloUwbApp -->|"hosts"| AppNavGraph
    AppNavGraph -->|navigates to| MainActivity
    MainActivity -->|calls| HomeVM
    MainActivity -->|calls| ControlVM
    MainActivity -->|calls| SendVM
    MainActivity -->|calls| SettingsVM
    MainActivity -->|calls| RangingVM
    HomeVM -->|gets| AppContainer
    ControlVM -->|gets| AppContainer
    SendVM -->|gets| AppContainer
    SettingsVM -->|gets| AppContainer
    RangingVM -->|gets| AppContainer
    AppContainer -->|provides| SettingsStore
    AppContainer -->|provides| ControlSource
    SettingsStoreImpl -->|implements| SettingsStore
    ControlSourceImpl -->|implements| ControlSource
    ControlSourceImpl -->|calls| UwbConnMgrImpl
    ProtoDataStore -->|backing| SettingsStoreImpl

    NearbyConn -->|"over transport"| GoogleNearby
    NearbyConnector -->|"over transport"| GoogleNearby
    NearbyCtrlConnector -->|"over transport"| GoogleNearby
    NearbyControleeConnector -->|"over transport"| GoogleNearby
    OobConnector -->|"over transport"| GoogleNearby
    GoogleNearby -->|to hardware| AndroidUWB

    %% Click Events
    click HelloUwbApp "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/HelloUwbApplication.kt"
    click AppContainer "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/AppContainer.kt"
    click AppContainerImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/data/AppContainerImpl.kt"
    click SettingsStore "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/data/SettingsStore.kt"
    click SettingsStoreImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/data/SettingsStoreImpl.kt"
    click ControlSource "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/data/UwbRangingControlSource.kt"
    click ControlSourceImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/data/UwbRangingControlSourceImpl.kt"
    click HelloUwbApp "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/HelloUwbApp.kt"
    click MainActivity "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/MainActivity.kt"
    click AppNavGraph "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/nav/AppNavGraph.kt"
    click HomeVM "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/home/HomeViewModel.kt"
    click ControlVM "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/control/ControlViewModel.kt"
    click SendVM "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/send/SendViewModel.kt"
    click SettingsVM "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/settings/SettingsViewModel.kt"
    click RangingVM "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/java/com/google/apps/hellouwb/ui/ranging/RangingViewModel.kt"
    click UwbConnMgr "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/UwbConnectionManager.kt"
    click UwbEndpoint "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/UwbEndpoint.kt"
    click EndpointEvents "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/EndpointEvents.kt"
    click UwbSessionScope "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/UwbSessionScope.kt"
    click NearbyConn "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/NearbyConnections.kt"
    click NearbyConnector "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/NearbyConnector.kt"
    click NearbyCtrlConnector "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/NearbyControllerConnector.kt"
    click NearbyControleeConnector "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/NearbyControleeConnector.kt"
    click OobConnector "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/OobConnector.kt"
    click UwbConnMgrImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/UwbConnectionManagerImpl.kt"
    click UwbOobEvent "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/UwbOobEvent.kt"
    click UwbSessionScopeImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/java/com/google/apps/uwbranging/impl/UwbSessionScopeImpl.kt"
    click ProtoDataStore "https://github.com/android/connectivity-samples/blob/main/UwbRanging/app/src/main/proto/appsetttings.proto"
    click UwbConnMgrImpl "https://github.com/android/connectivity-samples/blob/main/UwbRanging/uwbranging/src/main/proto/uwbinfo.proto"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0277BD
    classDef vm fill:#DFFFD6,stroke:#558B2F
    classDef data fill:#FFF5BA,stroke:#FFB300
    classDef lib fill:#E1D7FF,stroke:#6A1B9A
    classDef external fill:#E0E0E0,stroke:#424242
```
