# farazkayan/soundmesh architecture

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

- Interactive diagram: https://gitdiagram.com/farazkayan/soundmesh
- Repository: https://github.com/farazkayan/soundmesh

## Overview

SoundMesh is a local-first Flutter/Android app that turns nearby Android phones into a synchronized speaker system. Its user workflow is to create a room and show a QR code, have participants join, then capture host audio, distribute PCM packets, buffer them on participants, and schedule local playback against a shared timeline. The graph preserves room discovery and timing calibration as distinct stages. Flutter orchestration and synchronization details are mostly unsampled, so those relationships are documented at a high level; dashed edges mark links not verified in the excerpts.

Main entry points: [`app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt`](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt) (Audio capture), [`app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt`](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt) (Receive buffer), [`app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt`](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt) (Audio transport), [`app/android/app/src/main/kotlin/com/soundmesh/soundmesh/output/AudioOutputEngine.kt`](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/output/AudioOutputEngine.kt) (Scheduled output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_screens["Room screens"]
  node_room_flow["Room flows"]
  node_flutter_entry["Flutter entry<br/>[main.dart]"]
  node_native_bridge["Platform bridge<br/>[MainActivity.kt]"]
end

subgraph group_room["Room coordination"]
  node_discovery["Room discovery"]
  node_discovery_manager["Discovery manager"]
  node_protocol["Room protocol"]
end

subgraph group_audio["Audio pipeline"]
  node_capture["Audio capture"]
  node_capture_service["Capture service"]
  node_capture_permission["Capture consent"]
  node_audio_transport["Audio transport"]
  node_packet_format["Audio packet<br/>[AudioPacket.kt]"]
  node_receive_buffer["Receive buffer"]
  node_frame_decoder["Frame decoder<br/>[FrameDecoder.kt]"]
end

subgraph group_timing["Timing and playback"]
  node_sync["Clock synchronization"]
  node_timeline["Shared timeline"]
  node_output["Scheduled output"]
end

node_user(("Phone user"))
node_local_speakers(("Phone speakers"))

node_user -->|"uses"| node_screens
node_screens -.->|"starts room flow"| node_room_flow
node_room_flow -.->|"joins room"| node_discovery_manager
node_discovery_manager -.->|"discovers nearby"| node_discovery
node_user -->|"scans QR"| node_discovery
node_flutter_entry -.->|"bridges native audio"| node_native_bridge
node_native_bridge -.->|"starts capture"| node_capture
node_capture -->|"requests consent"| node_capture_permission
node_capture -->|"starts foreground"| node_capture_service
node_capture -->|"sends PCM frames"| node_audio_transport
node_audio_transport -->|"serializes frames"| node_packet_format
node_audio_transport -->|"transmits packets"| node_receive_buffer
node_receive_buffer -.->|"buffers packets"| node_packet_format
node_receive_buffer -.->|"decodes frames"| node_frame_decoder
node_receive_buffer -->|"feeds playback"| node_output
node_protocol -.->|"carries timing messages"| node_sync
node_sync -->|"calibrates timeline"| node_timeline
node_timeline -->|"schedules playback"| node_output
node_output -->|"plays locally"| node_local_speakers

click node_screens "https://github.com/farazkayan/soundmesh/tree/main/app/lib/presentation/screens"
click node_room_flow "https://github.com/farazkayan/soundmesh/tree/main/app/lib/application/providers"
click node_flutter_entry "https://github.com/farazkayan/soundmesh/blob/main/app/lib/main.dart"
click node_native_bridge "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/MainActivity.kt"
click node_discovery "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/discovery/DiscoveryService.kt"
click node_discovery_manager "https://github.com/farazkayan/soundmesh/blob/main/app/lib/infrastructure/discovery/discovery_manager.dart"
click node_protocol "https://github.com/farazkayan/soundmesh/blob/main/app/lib/application/protocol/protocol_message.dart"
click node_capture "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt"
click node_capture_service "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureService.kt"
click node_capture_permission "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/MediaProjectionHelper.kt"
click node_audio_transport "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt"
click node_packet_format "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioPacket.kt"
click node_receive_buffer "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt"
click node_frame_decoder "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/FrameDecoder.kt"
click node_sync "https://github.com/farazkayan/soundmesh/tree/main/app/lib/application/synchronization"
click node_timeline "https://github.com/farazkayan/soundmesh/blob/main/app/lib/application/providers/timeline_provider.dart"
click node_output "https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/output/AudioOutputEngine.kt"

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_screens,node_room_flow,node_flutter_entry,node_native_bridge,node_user toneBlue
class node_discovery,node_discovery_manager,node_protocol toneAmber
class node_capture,node_capture_service,node_capture_permission,node_audio_transport,node_packet_format,node_receive_buffer,node_frame_decoder toneMint
class node_sync,node_timeline,node_output toneRose
class node_local_speakers toneIndigo
```

## Components

### App experience

- [Room screens](https://github.com/farazkayan/soundmesh/tree/main/app/lib/presentation/screens): `app/lib/presentation/screens`
- [Room flows](https://github.com/farazkayan/soundmesh/tree/main/app/lib/application/providers): `app/lib/application/providers`
- [Flutter entry](https://github.com/farazkayan/soundmesh/blob/main/app/lib/main.dart): `app/lib/main.dart`
- [Platform bridge](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/MainActivity.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/MainActivity.kt`

### Room coordination

- [Room discovery](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/discovery/DiscoveryService.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/discovery/DiscoveryService.kt`
- [Discovery manager](https://github.com/farazkayan/soundmesh/blob/main/app/lib/infrastructure/discovery/discovery_manager.dart): `app/lib/infrastructure/discovery/discovery_manager.dart`
- [Room protocol](https://github.com/farazkayan/soundmesh/blob/main/app/lib/application/protocol/protocol_message.dart): `app/lib/application/protocol/protocol_message.dart`

### Audio pipeline

- [Audio capture](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt`
- [Capture service](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureService.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureService.kt`
- [Capture consent](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/MediaProjectionHelper.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/MediaProjectionHelper.kt`
- [Audio transport](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt`
- [Audio packet](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioPacket.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioPacket.kt`
- [Receive buffer](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt`
- [Frame decoder](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/FrameDecoder.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/FrameDecoder.kt`

### Timing and playback

- [Clock synchronization](https://github.com/farazkayan/soundmesh/tree/main/app/lib/application/synchronization): `app/lib/application/synchronization`
- [Shared timeline](https://github.com/farazkayan/soundmesh/blob/main/app/lib/application/providers/timeline_provider.dart): `app/lib/application/providers/timeline_provider.dart`
- [Scheduled output](https://github.com/farazkayan/soundmesh/blob/main/app/android/app/src/main/kotlin/com/soundmesh/soundmesh/output/AudioOutputEngine.kt): `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/output/AudioOutputEngine.kt`

### Other components

- **Phone user**
- **Phone speakers**

## Connections

- Phone user → Room screens: uses (evidence: `README.md`)
- Room screens → Room flows: starts room flow
- Room flows → Discovery manager: joins room
- Discovery manager → Room discovery: discovers nearby
- Phone user → Room discovery: scans QR (evidence: `README.md`)
- Flutter entry → Platform bridge: bridges native audio
- Platform bridge → Audio capture: starts capture (evidence: `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/MainActivity.kt`)
- Audio capture → Capture consent: requests consent (evidence: `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt`)
- Audio capture → Capture service: starts foreground (evidence: `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/capture/AudioCaptureEngine.kt`)
- Audio capture → Audio transport: sends PCM frames (evidence: `README.md`)
- Audio transport → Audio packet: serializes frames (evidence: `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioTransportEngine.kt`)
- Audio transport → Receive buffer: transmits packets (evidence: `README.md`)
- Receive buffer → Audio packet: buffers packets (evidence: `app/android/app/src/main/kotlin/com/soundmesh/soundmesh/transport/AudioReceiveEngine.kt`)
- Receive buffer → Frame decoder: decodes frames
- Receive buffer → Scheduled output: feeds playback (evidence: `README.md`)
- Room protocol → Clock synchronization: carries timing messages
- Clock synchronization → Shared timeline: calibrates timeline (evidence: `README.md`)
- Shared timeline → Scheduled output: schedules playback (evidence: `README.md`)
- Scheduled output → Phone speakers: plays locally (evidence: `README.md`)
