# nisargjhaveri/aawirelessgateway architecture

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

- Interactive diagram: https://gitdiagram.com/nisargjhaveri/aawirelessgateway
- Repository: https://github.com/nisargjhaveri/aawirelessgateway

## Overview

##### Project type and purpose
- This is an Android mobile application (single Gradle module under `app/`) that enables Wireless Android Auto by acting as a gateway/proxy between a car’s wired Android Auto head unit and a phone (wireless client).
- The app can run in two modes:
- Gateway mode (installed on the device plugged into the car’s USB)
- Wireless-client mode (installed on the phone that will connect wirelessly)

##### High-level architecture
- Car head unit
- Gateway device (Android phone/tablet)
- Wireless-client device (Android phone/tablet)

– USBReceiverActivity (listens for Android Auto USB accessory attach)
– AAGatewayService (foreground service that orchestrates everything)
– AndroidAutoHelper (invokes native AA APIs)
– WifiHotspotHandler (enables/disables Android hotspot)
– BluetoothProfileHandler & BluetoothHandler (sets up Bluetooth server, incoming RFCOMM socket)
– Proto-generated classes (from `app/src/main/proto`) to serialize/deserialize control messages

– AAWirelessClientService (foreground service in client mode)
– AndroidAutoHelper (starts native wireless AA)
– BluetoothReceiver (connects to gateway’s Bluetooth socket)
– WifiClientHandler (connects to gateway’s hotspot)
– Proto-generated classes (same message definitions)

##### Interactions and data flows
- WifiInfoRequest, WifiStartRequest → for communicating SSID, credentials
- Client uses WifiClientHandler to join the hotspot and then AndroidAutoHelper to start AA
- (Optional) Direct USB fallback path on gateway if wireless fails (via root/system app)

##### Architectural patterns and design principles
- Separation of concerns: distinct Handler classes for USB, Bluetooth, Wi-Fi and a central Service (`AAGatewayService` / `AAWirelessClientService`)
- Event-driven Android components: Activities and BroadcastReceivers trigger Services
- Protocol abstraction: `.proto` files define the control‐plane messages, keeping serialization independent of transport
- Foreground services ensure the app stays alive only when needed (no always-on background)

##### Technologies and frameworks
- Android SDK: Activities, Services, BroadcastReceivers
- Android Accessory / USB Host APIs for Android Auto over USB
- Android Wi-Fi Hotspot APIs (`WifiManager` + connectivity intents)
- Android Bluetooth APIs (`BluetoothAdapter`, `BluetoothServerSocket`, `BluetoothSocket`)
- Protocol Buffers (via `app/src/main/proto`)
- Gradle build system and ProGuard rules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Car Head Unit
    subgraph "Car Head Unit" 
        direction TB
        CarHead["Car Head Unit"]:::car
    end

    %% Gateway Device
    subgraph "Gateway Device" 
        direction TB
        USBReceiverActivity["USBReceiverActivity"]:::gateway
        AAGatewayService["AAGatewayService"]:::gateway
        AndroidAutoHelperGW["AndroidAutoHelper"]:::gateway
        WifiHotspotHandler["WifiHotspotHandler"]:::gateway
        BluetoothProfileHandler["BluetoothProfileHandler"]:::gateway
        BluetoothHandler["BluetoothHandler"]:::gateway
        ProtoGW1["WifiInfoRequest.proto"]:::proto
        ProtoGW2["WifiStartRequest.proto"]:::proto
    end

    %% Wireless Client Device
    subgraph "Wireless Client Device"
        direction TB
        AAWirelessClientService["AAWirelessClientService"]:::client
        AndroidAutoHelperCL["AndroidAutoHelper"]:::client
        BluetoothReceiver["BluetoothReceiver"]:::client
        WifiClientHandler["WifiClientHandler"]:::client
        ProtoCL1["WifiInfoRequest.proto"]:::proto
        ProtoCL2["WifiStartRequest.proto"]:::proto
    end

    %% Connections: USB
    CarHead -->|"USB Android Auto packets"| USBReceiverActivity
    USBReceiverActivity -->|"starts service"| AAGatewayService
    AAGatewayService -->|"invokes native AA APIs"| AndroidAutoHelperGW

    %% Connections: Bluetooth with protobuf
    BluetoothHandler -->|"RFCOMM/Bluetooth"| ProtoGW1
    BluetoothHandler -->|"RFCOMM/Bluetooth"| ProtoGW2
    ProtoGW1 -->|"protobuf messages"| BluetoothReceiver
    ProtoGW2 -->|"protobuf messages"| BluetoothReceiver

    %% Connections: Wi-Fi
    WifiHotspotHandler -->|"Wi-Fi network (IP data)"| WifiClientHandler
    WifiClientHandler -->|"joins hotspot then"| AndroidAutoHelperCL
    AAWirelessClientService -->|"starts native AA"| AndroidAutoHelperCL

    %% Direct USB fallback (optional)
    USBReceiverActivity -.->|"fallback USB"| AndroidAutoHelperGW

    %% Click Events
    click USBReceiverActivity "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/USBReceiverActivity.kt"
    click AAGatewayService "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/AAGatewayService.kt"
    click AndroidAutoHelperGW "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/AndroidAutoHelper.kt"
    click WifiHotspotHandler "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/WifiHotspotHandler.kt"
    click BluetoothProfileHandler "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/AABluetoothProfileHandler.kt"
    click BluetoothHandler "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/BluetoothHandler.kt"
    click ProtoGW1 "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/proto/com/nisargjhaveri/aagateway/WifiInfoRequest.proto"
    click ProtoGW2 "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/proto/com/nisargjhaveri/aagateway/WifiStartRequest.proto"
    click AAWirelessClientService "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/AAWirelessClientService.kt"
    click BluetoothReceiver "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/BluetoothReceiver.kt"
    click WifiClientHandler "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/java/com/nisargjhaveri/aagateway/WifiClientHandler.kt"
    click ProtoCL1 "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/proto/com/nisargjhaveri/aagateway/WifiInfoRequest.proto"
    click ProtoCL2 "https://github.com/nisargjhaveri/aawirelessgateway/blob/main/app/src/main/proto/com/nisargjhaveri/aagateway/WifiStartRequest.proto"

    %% Styles
    classDef gateway fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef client fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef car fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef proto fill:#FFF2CC,stroke:#666,stroke-dasharray: 2 2
    class CarHead car
    class USBReceiverActivity,AAGatewayService,AndroidAutoHelperGW,WifiHotspotHandler,BluetoothProfileHandler,BluetoothHandler gateway
    class AAWirelessClientService,AndroidAutoHelperCL,BluetoothReceiver,WifiClientHandler client
    class ProtoGW1,ProtoGW2,ProtoCL1,ProtoCL2 proto
    classDef transport fill:#FFE0B2,stroke:#E69A00,stroke-width:1px,stroke-dasharray: 2 2
```
