# n0tppan/phonebridge architecture

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

- Interactive diagram: https://gitdiagram.com/n0tppan/phonebridge
- Repository: https://github.com/n0tppan/phonebridge

## Overview

PhoneBridge streams Android camera video over USB/ADB to a Windows virtual webcam. The principal path is phone capture and packetization, PC connection and decoding, shared-frame delivery, then consumption by Windows camera clients; the desktop app controls the engine. The README also documents audio capture/control, driver installation, and the UI/status workflow, though Windows microphone output remains pending. Some implementation links are documented rather than visible in sampled code; those are cited to the README, and unsampled subsystems are not expanded beyond supported paths.

Main entry points: [`android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt`](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt) (Socket bridge), [`windows/service/connection/connection_manager.cpp`](https://github.com/n0tppan/phonebridge/blob/main/windows/service/connection/connection_manager.cpp) (Connection manager), [`windows/app/PhoneBridge/MainWindow.xaml.cs`](https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/MainWindow.xaml.cs) (Windows app), [`windows/service/main.cpp`](https://github.com/n0tppan/phonebridge/blob/main/windows/service/main.cpp) (Engine entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android capture"]
  node_android_ui["Android controls<br/>[MainScreen.kt]"]
  node_bridge_service["Bridge service<br/>[BridgeService.kt]"]
  node_bridge_server["Socket bridge<br/>[BridgeServer.kt]"]
  node_camera_capture["Camera encoder<br/>[CameraEncoder.kt]"]
  node_audio_capture["Audio recorder<br/>[AudioRecorder.kt]"]
end

subgraph group_protocol["Wire protocol"]
  node_android_protocol["Android protocol<br/>[Protocol.kt]"]
  node_packet_format["Packet format<br/>[packet.h]"]
  node_packet_parser["Packet parser<br/>[packet_parser.cpp]"]
end

subgraph group_engine["Windows engine"]
  node_engine_entry["Engine entry<br/>[main.cpp]"]
  node_adb_transport["ADB transport<br/>[adb_transport.cpp]"]
  node_connection["Connection manager"]
  node_video_receiver["Video receiver<br/>[video_receiver.cpp]"]
  node_h264_decoder["H.264 decoder<br/>[h264_decoder.cpp]"]
  node_audio_receiver["Audio receiver<br/>[audio_receiver.cpp]"]
end

subgraph group_camera["Virtual camera"]
  node_shared_frames["Shared frames<br/>[shared_frame.h]"]
  node_media_source["Media Foundation source"]
  node_media_stream["Media stream"]
  node_directshow_camera["DirectShow camera"]
end

subgraph group_desktop["Desktop control"]
  node_windows_app["Windows app<br/>[MainWindow.xaml.cs]"]
  node_host_bridge["Host bridge<br/>[HostBridge.cs]"]
  node_engine_client["Engine client<br/>[EngineClient.cs]"]
  node_react_ui["Desktop UI<br/>[App.tsx]"]
  node_ui_bridge["UI bridge<br/>[bridge.ts]"]
  node_driver_installer["Camera installer<br/>[DriverInstaller.cs]"]
end

node_phone_user(("Phone user"))
node_adb["ADB over USB"]
node_camera_clients(("Windows camera clients"))

node_phone_user -->|"starts capture"| node_android_ui
node_android_ui -->|"starts service"| node_bridge_service
node_bridge_service -->|"starts server"| node_bridge_server
node_bridge_server -->|"requests frames"| node_camera_capture
node_bridge_server -->|"requests audio"| node_audio_capture
node_bridge_server -->|"encodes packets"| node_android_protocol
node_android_protocol -.->|"uses format"| node_packet_format
node_bridge_server -->|"sends stream"| node_adb
node_adb -->|"forwards socket"| node_adb_transport
node_engine_entry -->|"creates transport"| node_adb_transport
node_engine_entry -->|"starts manager"| node_connection
node_connection -.->|"connects and reads"| node_adb_transport
node_connection -->|"parses packets"| node_packet_parser
node_connection -->|"dispatches video"| node_video_receiver
node_connection -->|"dispatches audio"| node_audio_receiver
node_video_receiver -->|"decodes frames"| node_h264_decoder
node_h264_decoder -->|"writes frames"| node_shared_frames
node_media_source -->|"reads frames"| node_shared_frames
node_media_source -->|"creates stream"| node_media_stream
node_media_stream -->|"delivers frames"| node_camera_clients
node_phone_user -->|"controls session"| node_windows_app
node_windows_app -.->|"hosts UI"| node_host_bridge
node_host_bridge -.->|"controls engine"| node_engine_client
node_engine_client -->|"launches process"| node_engine_entry
node_react_ui -->|"sends commands"| node_ui_bridge
node_ui_bridge -.->|"exchanges messages"| node_host_bridge
node_windows_app -->|"installs camera"| node_driver_installer
node_camera_clients -.->|"may use"| node_directshow_camera

click node_android_ui "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/ui/MainScreen.kt"
click node_bridge_service "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/bridge/BridgeService.kt"
click node_bridge_server "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt"
click node_camera_capture "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/camera/CameraEncoder.kt"
click node_audio_capture "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/audio/AudioRecorder.kt"
click node_android_protocol "https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/protocol/Protocol.kt"
click node_packet_format "https://github.com/n0tppan/phonebridge/blob/main/protocol/packet.h"
click node_packet_parser "https://github.com/n0tppan/phonebridge/blob/main/protocol/packet_parser.cpp"
click node_engine_entry "https://github.com/n0tppan/phonebridge/blob/main/windows/service/main.cpp"
click node_adb_transport "https://github.com/n0tppan/phonebridge/blob/main/windows/service/transport/adb_transport.cpp"
click node_connection "https://github.com/n0tppan/phonebridge/blob/main/windows/service/connection/connection_manager.cpp"
click node_video_receiver "https://github.com/n0tppan/phonebridge/blob/main/windows/service/video/video_receiver.cpp"
click node_h264_decoder "https://github.com/n0tppan/phonebridge/blob/main/windows/service/video/h264_decoder.cpp"
click node_audio_receiver "https://github.com/n0tppan/phonebridge/blob/main/windows/service/audio/audio_receiver.cpp"
click node_shared_frames "https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/shared_frame.h"
click node_media_source "https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/phonebridge_media_source.cpp"
click node_media_stream "https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/phonebridge_media_stream.cpp"
click node_windows_app "https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/MainWindow.xaml.cs"
click node_host_bridge "https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/HostBridge.cs"
click node_engine_client "https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/EngineClient.cs"
click node_react_ui "https://github.com/n0tppan/phonebridge/blob/main/ui/src/App.tsx"
click node_ui_bridge "https://github.com/n0tppan/phonebridge/blob/main/ui/src/bridge.ts"
click node_driver_installer "https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/DriverInstaller.cs"
click node_directshow_camera "https://github.com/n0tppan/phonebridge/blob/main/windows/directshow-camera/phonebridge_filter.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android_ui,node_bridge_service,node_bridge_server,node_camera_capture,node_audio_capture,node_phone_user,node_camera_clients toneBlue
class node_android_protocol,node_packet_format,node_packet_parser toneAmber
class node_engine_entry,node_adb_transport,node_connection,node_video_receiver,node_h264_decoder,node_audio_receiver toneMint
class node_shared_frames,node_media_source,node_media_stream,node_directshow_camera toneRose
class node_windows_app,node_host_bridge,node_engine_client,node_react_ui,node_ui_bridge,node_driver_installer,node_adb toneIndigo
```

## Components

### Android capture

- [Android controls](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/ui/MainScreen.kt): `android/app/src/main/java/com/phonebridge/ui/MainScreen.kt`
- [Bridge service](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/bridge/BridgeService.kt): `android/app/src/main/java/com/phonebridge/bridge/BridgeService.kt`
- [Socket bridge](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt): `android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt`
- [Camera encoder](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/camera/CameraEncoder.kt): `android/app/src/main/java/com/phonebridge/camera/CameraEncoder.kt`
- [Audio recorder](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/audio/AudioRecorder.kt): `android/app/src/main/java/com/phonebridge/audio/AudioRecorder.kt`

### Wire protocol

- [Android protocol](https://github.com/n0tppan/phonebridge/blob/main/android/app/src/main/java/com/phonebridge/protocol/Protocol.kt): `android/app/src/main/java/com/phonebridge/protocol/Protocol.kt`
- [Packet format](https://github.com/n0tppan/phonebridge/blob/main/protocol/packet.h): `protocol/packet.h`
- [Packet parser](https://github.com/n0tppan/phonebridge/blob/main/protocol/packet_parser.cpp): `protocol/packet_parser.cpp`

### Windows engine

- [Engine entry](https://github.com/n0tppan/phonebridge/blob/main/windows/service/main.cpp): `windows/service/main.cpp`
- [ADB transport](https://github.com/n0tppan/phonebridge/blob/main/windows/service/transport/adb_transport.cpp): `windows/service/transport/adb_transport.cpp`
- [Connection manager](https://github.com/n0tppan/phonebridge/blob/main/windows/service/connection/connection_manager.cpp): `windows/service/connection/connection_manager.cpp`
- [Video receiver](https://github.com/n0tppan/phonebridge/blob/main/windows/service/video/video_receiver.cpp): `windows/service/video/video_receiver.cpp`
- [H.264 decoder](https://github.com/n0tppan/phonebridge/blob/main/windows/service/video/h264_decoder.cpp): `windows/service/video/h264_decoder.cpp`
- [Audio receiver](https://github.com/n0tppan/phonebridge/blob/main/windows/service/audio/audio_receiver.cpp): `windows/service/audio/audio_receiver.cpp`

### Virtual camera

- [Shared frames](https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/shared_frame.h): `windows/virtual-camera/shared_frame.h`
- [Media Foundation source](https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/phonebridge_media_source.cpp): `windows/virtual-camera/phonebridge_media_source.cpp`
- [Media stream](https://github.com/n0tppan/phonebridge/blob/main/windows/virtual-camera/phonebridge_media_stream.cpp): `windows/virtual-camera/phonebridge_media_stream.cpp`
- [DirectShow camera](https://github.com/n0tppan/phonebridge/blob/main/windows/directshow-camera/phonebridge_filter.cpp): `windows/directshow-camera/phonebridge_filter.cpp`

### Desktop control

- [Windows app](https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/MainWindow.xaml.cs): `windows/app/PhoneBridge/MainWindow.xaml.cs`
- [Host bridge](https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/HostBridge.cs): `windows/app/PhoneBridge/Core/HostBridge.cs`
- [Engine client](https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/EngineClient.cs): `windows/app/PhoneBridge/Core/EngineClient.cs`
- [Desktop UI](https://github.com/n0tppan/phonebridge/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [UI bridge](https://github.com/n0tppan/phonebridge/blob/main/ui/src/bridge.ts): `ui/src/bridge.ts`
- [Camera installer](https://github.com/n0tppan/phonebridge/blob/main/windows/app/PhoneBridge/Core/DriverInstaller.cs): `windows/app/PhoneBridge/Core/DriverInstaller.cs`

### Other components

- **Phone user**
- **ADB over USB**
- **Windows camera clients**

## Connections

- Phone user → Android controls: starts capture
- Android controls → Bridge service: starts service (evidence: `android/app/src/main/java/com/phonebridge/ui/MainActivity.kt`)
- Bridge service → Socket bridge: starts server (evidence: `android/app/src/main/java/com/phonebridge/bridge/BridgeService.kt`)
- Socket bridge → Camera encoder: requests frames (evidence: `android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt`)
- Socket bridge → Audio recorder: requests audio (evidence: `android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt`)
- Socket bridge → Android protocol: encodes packets (evidence: `android/app/src/main/java/com/phonebridge/bridge/BridgeServer.kt`)
- Android protocol → Packet format: uses format
- Socket bridge → ADB over USB: sends stream
- ADB over USB → ADB transport: forwards socket
- Engine entry → ADB transport: creates transport (evidence: `windows/service/main.cpp`)
- Engine entry → Connection manager: starts manager (evidence: `windows/service/main.cpp`)
- Connection manager → ADB transport: connects and reads
- Connection manager → Packet parser: parses packets (evidence: `windows/service/connection/connection_manager.cpp`)
- Connection manager → Video receiver: dispatches video (evidence: `windows/service/connection/connection_manager.cpp`)
- Connection manager → Audio receiver: dispatches audio (evidence: `windows/service/connection/connection_manager.cpp`)
- Video receiver → H.264 decoder: decodes frames
- H.264 decoder → Shared frames: writes frames
- Media Foundation source → Shared frames: reads frames
- Media Foundation source → Media stream: creates stream (evidence: `windows/virtual-camera/phonebridge_media_source.cpp`)
- Media stream → Windows camera clients: delivers frames
- Phone user → Windows app: controls session
- Windows app → Host bridge: hosts UI
- Host bridge → Engine client: controls engine
- Engine client → Engine entry: launches process
- Desktop UI → UI bridge: sends commands (evidence: `ui/src/App.tsx`)
- UI bridge → Host bridge: exchanges messages
- Windows app → Camera installer: installs camera
- Windows camera clients → DirectShow camera: may use