# skollip/bluetooth-walkie-talkie architecture

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

- Interactive diagram: https://gitdiagram.com/skollip/bluetooth-walkie-talkie
- Repository: https://github.com/skollip/bluetooth-walkie-talkie

## Overview

##### Project type & purpose (from README + tree)
This is a **native Android application** (“Push to Talk” walkie-talkie) that uses **Bluetooth** to create a peer-to-peer connection and transmit audio while a user holds a microphone button (PTT). It’s not a client/server web system; the “system” is primarily **an Android app + Android Bluetooth stack + a peer Android device**.

Key evidence:
- `src/AndroidManifest.xml` → Android app
- `src/build.gradle` → Android build
- Core Java classes: `ConnectThread.java`, `ListenThread.java`, `MainConversation.java`, `UserSelection.java`
- Layout: `activity_user_selection.xml`
- Prebuilt APK: `bin/WalkieTalkie.apk`
- Root HTML files (`index.html`, `software.html`, etc.) look like **project documentation**, not runtime components.

##### What the file structure tells you architecturally
Treat these as your main “modules” when drawing components:

##### Runtime code (Android app)
- **Activities / UI layer**
- `UserSelection.java` + `activity_user_selection.xml`
Likely handles device discovery/selection and initiating connection.
- `MainConversation.java`
Likely the “PTT” screen: capture mic, send audio, receive audio, playback.
- **Bluetooth connection management**
- `ConnectThread.java`
Outgoing connection logic (client role) using `BluetoothSocket.connect()`.
- `ListenThread.java`
Incoming connection logic (server role) using `BluetoothServerSocket.accept()`.
- **Model / data**
- `DeviceInfo.java`
Likely encapsulates Bluetooth device metadata (name, MAC, etc.).

##### Non-runtime artifacts (do not confuse with system components)
- `bin/` contains packaged output + some HTML
- `doc/`, `data/`, root `*.html`, `finalReport.*` are documentation/reporting assets

##### Device/Platform boundary
- **Android Device A** (your app process)
- **Android Device B** (peer app process)
- **Android OS services** (Bluetooth stack, audio stack)
- **Bluetooth Radio / Link** between devices

##### Application internal subsystems
Inside each device, break the app into:
##### Bluetooth Transport Layer
- `ListenThread` (server accept loop)
- `ConnectThread` (client connect)
- **BluetoothSocket I/O** (InputStream/OutputStream)
##### Audio Pipeline
- **Audio Capture** (e.g., `AudioRecord`) → produces PCM frames
- **Audio Playback** (e.g., `AudioTrack`) ← consumes PCM frames
- (If the code compresses/frames audio, represent an **Audio Framing/Codec** block; if not obvious, label it “PCM frames / raw audio”)
##### Session/State
- Connected/Disconnected state
- Selected device identity (`DeviceInfo`)
- Push-to-talk state (button held → transmit mode)

##### Discovery/Selection → Connection
- `UserSelection` triggers connect:
- UI event (“Connect”) → `ConnectThread.start()` (client role)
- Or app listens:
- App starts `ListenThread.start()` (server role) awaiting incoming connection

##### Connection → Socket Established
- `ConnectThread` → Android Bluetooth API → BluetoothSocket (connected)
- `ListenThread` → Android Bluetooth API → BluetoothServerSocket.accept()` → BluetoothSocket (connected)

##### Push-to-Talk Audio Transmit
- PTT button down (in `MainConversation`) → Audio Capture starts
- Audio frames → (optional framing/encoding) → BluetoothSocket OutputStream → Bluetooth link → peer InputStream

##### Audio Receive/Playback
- BluetoothSocket InputStream → (optional deframe/decode) → Audio Playback

##### Concurrency explicitly
- UI thread (Activities)
- Connection threads (listen/connect)
- I/O loop thread(s) (often same as connect/listen thread post-connection, or separate)
- Audio capture/playback running loops (could be separate threads or within main conversation logic)

##### Architectural patterns to highlight (based on this structure)
This is effectively:
- **Layered architecture** inside the app:
- Presentation (Activities + XML)
- Transport (Bluetooth threads + sockets)
- Media (capture/playback)
- **Peer-to-peer** topology:
- Either device can act as **server (listener)** or **client (connector)**.
- **Event-driven UI** controlling long-running background operations:

- Android SDK / Gradle build (`build.gradle`)
- Android Bluetooth APIs:
- `BluetoothAdapter`, `BluetoothDevice`, `BluetoothServerSocket`, `BluetoothSocket`
- Android Audio APIs (very likely even if not visible in tree):
- `AudioRecord` (capture), `AudioTrack` (playback)
- Threading model:
- Java Threads / Android main thread

##### Diagramming rules to follow (so it’s readable and unambiguous)
Elements explicitly:

##### Clear labels
- Use exact class names where relevant: `ConnectThread`, `ListenThread`, `MainConversation`, `UserSelection`, `DeviceInfo`

- “PCM frames / audio bytes”
- “Bluetooth socket stream”
- “Connection status/events”

##### Boundaries
- App Process
- Android OS
- Hardware/Radio
- Remote peer device

##### Practical “don’t overthink it” decomposition (maximize components)
- Split “Bluetooth” into: Adapter/Discovery, Connect, Listen, Socket I/O
- Split “Audio” into: Capture, Buffering/Framing, Playback
- Split “UI” into screens and key UI events (connect/disconnect/PTT press)
Even if some of these are implemented in the same class, representing them separately makes the architecture easier to reason about.

Before finalizing, quickly scan:
- `AndroidManifest.xml` for:
- Permissions: `BLUETOOTH`, `BLUETOOTH_ADMIN`, `RECORD_AUDIO`
- Bluetooth feature flags
- `ConnectThread.java` and `ListenThread.java` for:
- UUID/service name (RFCOMM service UUID)
- Who closes sockets, lifecycle handling
- `MainConversation.java` for:
- Whether audio is raw PCM vs encoded
- Threading model for audio loops
- `UserSelection.java` for:
- Discovery mechanism (paired devices only vs discovery scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% View 1: System Context
%% =========================
subgraph V1["View 1: System Context (Device-to-Device)"]
direction TB

subgraph DA["Android Device A"]
direction TB
AAPP["WalkieTalkie App (Process)"]:::app
AOS["Android OS Services"]:::os
ABT["Android Bluetooth Stack\n(BluetoothAdapter/BluetoothSocket)"]:::os
AAUD["Android Audio APIs\n(AudioRecord/AudioTrack)"]:::os
AHW["Hardware\n(Mic/Speaker/Bluetooth Radio)"]:::hw

AAPP --> AOS
AOS --> ABT
AOS --> AAUD
ABT --> AHW
AAUD --> AHW
end

BL["Bluetooth Link\n(RFCOMM socket stream)"]:::link

subgraph DB["Android Device B"]
direction TB
BAPP["WalkieTalkie App (Process)"]:::app
BOS["Android OS Services"]:::os
BBT["Android Bluetooth Stack\n(BluetoothAdapter/BluetoothSocket)"]:::os
BAUD["Android Audio APIs\n(AudioRecord/AudioTrack)"]:::os
BHW["Hardware\n(Mic/Speaker/Bluetooth Radio)"]:::hw

BAPP --> BOS
BOS --> BBT
BOS --> BAUD
BBT --> BHW
BAUD --> BHW
end

AHW -->|"radio"| BL
BL -->|"radio"| BHW
end

%% =========================
%% View 2: Container/Subsystem (Single Device)
%% =========================
subgraph V2["View 2: Inside WalkieTalkie App (Single Device)"]
direction TB

subgraph PROC["App Process"]
direction TB

subgraph UI["UI / Presentation (Main Thread)"]
direction TB
US["UserSelection (Activity)\nDevice discovery/selection + Connect"]:::ui
USL["activity_user_selection.xml (Layout)"]:::ui
MC["MainConversation (Activity)\nPush-to-Talk screen"]:::ui
MIC["Mic Icon Drawable"]:::asset
STATE["Session/State\n(Connected/Disconnected,\nSelected device, PTT state)"]:::state
end

subgraph BT["Bluetooth Transport Layer (Background Threads)"]
direction TB
DISC["BluetoothAdapter\n(Paired devices / discovery)"]:::os
CT["ConnectThread (Client)\nBluetoothSocket.connect()"]:::thread
LT["ListenThread (Server)\nBluetoothServerSocket.accept()"]:::thread
SOCK["BluetoothSocket I/O\n(InputStream/OutputStream)"]:::socket
end

subgraph AUD["Audio Pipeline"]
direction TB
CAP["Audio Capture\n(AudioRecord loop)"]:::audio
FRM["Audio framing/PCM buffers\n(raw audio bytes)"]:::audio
PLY["Audio Playback\n(AudioTrack loop)"]:::audio
end

MODEL["DeviceInfo (Model)\n(name, MAC, etc.)"]:::model

%% UI wiring
US -->|"inflates"| USL
MC -->|"uses"| MIC

%% Control (dashed)
US -.->|"selects_device"| MODEL
US -.->|"updates"| STATE
MC -.->|"updates"| STATE

US -.->|"starts_listen()"| LT
US -.->|"starts_connect()"| CT
MC -.->|"connect_or_disconnect"| CT
MC -.->|"connect_or_disconnect"| LT

%% Bluetooth dependencies
US -->|"uses"| DISC
CT -->|"calls"| ABTAPI["Android Bluetooth API\n(BluetoothDevice/BluetoothSocket)"]:::os
LT -->|"calls"| ABTAPI
ABTAPI -->|"creates/returns"| SOCK

CT -->|"on_connected"| SOCK
LT -->|"on_accepted"| SOCK

%% Audio data flow (solid)
MC -.->|"PTT_down_start_capture"| CAP
MC -.->|"PTT_up_stop_capture"| CAP

CAP -->|"PCM_frames"| FRM
FRM -->|"audio_bytes_write"| SOCK
SOCK -->|"audio_bytes_read"| FRM
FRM -->|"PCM_frames"| PLY

%% Status/events back to UI (dashed)
SOCK -.->|"connection_status/events"| STATE
STATE -.->|"UI_updated_via_handler"| MC
STATE -.->|"UI_updated_via_handler"| US

end
end

%% =========================
%% View 3: Key Sequence (Connect + PTT)
%% =========================
subgraph V3["View 3: Sequence (Select device → Connect → PTT transmit → Release)"]
direction TB

subgraph SEQ["Lifelines"]
direction TB
U["User"]:::external
SUS["UserSelection"]:::ui
SMC["MainConversation"]:::ui
SCT["ConnectThread"]:::thread
SLT["ListenThread (Peer side)"]:::thread
SAPI["Android Bluetooth API"]:::os
SSOCKA["BluetoothSocket (A)"]:::socket
SSOCKB["BluetoothSocket (B)"]:::socket
SCAP["AudioRecord (A)"]:::audio
SPLY["AudioTrack (B)"]:::audio
end

U -.->|"select_device"| SUS
SUS -.->|"start_connectThread()"| SCT
SCT -.->|"connect()"| SAPI
SAPI -.->|"blocks/negotiates"| SLT
SLT -.->|"accept()"| SAPI
SAPI -.->|"socket_established"| SSOCKA
SAPI -.->|"socket_established"| SSOCKB
SUS -.->|"launch_main_conversation"| SMC

U -.->|"PTT_button_down"| SMC
SMC -.->|"start_capture_loop"| SCAP
SCAP -->|"PCM_frames"| SSOCKA
SSOCKA -->|"bt_stream"| SSOCKB
SSOCKB -->|"PCM_frames"| SPLY

U -.->|"PTT_button_up"| SMC
SMC -.->|"stop_capture_loop"| SCAP
end

%% =========================
%% Non-runtime / Repo Artifacts (separate, minimal)
%% =========================
subgraph NR["Non-runtime Artifacts (Documentation & Build Outputs)"]
direction TB
RD["README / Project Docs"]:::doc
SITE["Documentation Site Pages (HTML)"]:::doc
DOCF["doc/ (Folder)"]:::doc
DATAF["data/ (Folder)"]:::doc
FRPDF["finalReport.pdf"]:::doc
FRDOCX["finalReport.docx"]:::doc
APK["WalkieTalkie.apk (Build Artifact)"]:::artifact
GRADLE["Gradle Build Config"]:::artifact
MAN["AndroidManifest.xml\n(permissions, activities)"]:::artifact

GRADLE -.->|"builds"| APK
MAN -.->|"declares_permissions"| AAPP
RD -.->|"documents"| AAPP
SITE -.->|"documents"| AAPP
end

%% =========================
%% Click events (from component_mapping)
%% =========================
click MAN "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/AndroidManifest.xml"
click GRADLE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/build.gradle"
click US "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/UserSelection.java"
click USL "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/activity_user_selection.xml"
click MC "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/MainConversation.java"
click CT "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/ConnectThread.java"
click LT "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/ListenThread.java"
click MODEL "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/DeviceInfo.java"
click MIC "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/src/ic_mic_black_128dp.xml"
click APK "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/bin/WalkieTalkie.apk"
click RD "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/README.md"
click SITE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/index.html"
click SITE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/software.html"
click SITE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/hardware.html"
click SITE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/problemDescription.html"
click SITE "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/practicalProblems.html"
click DOCF "https://github.com/skollip/bluetooth-walkie-talkie/tree/master/doc/"
click DATAF "https://github.com/skollip/bluetooth-walkie-talkie/tree/master/data/"
click FRPDF "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/finalReport.pdf"
click FRDOCX "https://github.com/skollip/bluetooth-walkie-talkie/blob/master/finalReport.docx"

%% =========================
%% Styles (color-coded)
%% =========================
classDef ui fill:#1E88E5,stroke:#0D47A1,color:#FFFFFF,stroke-width:1.5px
classDef thread fill:#FB8C00,stroke:#E65100,color:#111111,stroke-width:1.5px
classDef os fill:#43A047,stroke:#1B5E20,color:#FFFFFF,stroke-width:1.5px
classDef audio fill:#00897B,stroke:#004D40,color:#FFFFFF,stroke-width:1.5px
classDef socket fill:#8E24AA,stroke:#4A148C,color:#FFFFFF,stroke-width:1.5px
classDef model fill:#6D4C41,stroke:#3E2723,color:#FFFFFF,stroke-width:1.5px
classDef state fill:#546E7A,stroke:#263238,color:#FFFFFF,stroke-width:1.5px
classDef link fill:#5E35B1,stroke:#311B92,color:#FFFFFF,stroke-width:2px
classDef hw fill:#90A4AE,stroke:#37474F,color:#111111,stroke-width:1.5px
classDef app fill:#3949AB,stroke:#1A237E,color:#FFFFFF,stroke-width:2px
classDef external fill:#FFFFFF,stroke:#424242,color:#111111,stroke-width:1.5px
classDef doc fill:#FDD835,stroke:#F57F17,color:#111111,stroke-width:1.5px
classDef artifact fill:#DCE775,stroke:#9E9D24,color:#111111,stroke-width:1.5px
classDef asset fill:#29B6F6,stroke:#01579B,color:#111111,stroke-width:1.5px
```
