# saibabooj/voicebridge architecture

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

- Interactive diagram: https://gitdiagram.com/saibabooj/voicebridge
- Repository: https://github.com/saibabooj/voicebridge

## Overview

VoiceBridge is a voice-first trip-planning and agreement demo for travellers and local drivers, with English, Hindi and Tamil interfaces. The workflow starts with language/trip setup and driver selection, continues through translated spoken chat and explicit confirmation of commitments, then locks a shared plan for the agreement; driver availability, tips, ratings and voice-key controls are supporting capabilities. The browser selects mock or WebSocket conversation transport and uses speech services for playback/transcription. Gateway routing and provider selection are evidenced; unsampled screen and transport internals are represented by their exact paths, with uncertain links omitted.

Main entry points: [`apps/web/src/screens/ChatScreen.tsx`](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/ChatScreen.tsx) (Traveller chat), [`apps/web/src/screens/DriverChatScreen.tsx`](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverChatScreen.tsx) (Driver chat), [`apps/web/src/lib/speech.ts`](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/speech.ts) (Speech client), [`apps/web/src/App.tsx`](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/App.tsx) (Route application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_journey["Trip setup and driver discovery"]
  node_language["Language setup<br/>[LanguageScreen.tsx]"]
  node_trip["Trip setup"]
  node_drivers["Driver discovery"]
  node_profile["Driver profile"]
end

subgraph group_conversation["Conversation and agreement"]
  node_travellerchat["Traveller chat<br/>[ChatScreen.tsx]"]
  node_driverchat["Driver chat"]
  node_messages["Translated messages<br/>[MessageBubble.tsx]"]
  node_confirm["Commitment confirmations<br/>[ConfirmBanner.tsx]"]
  node_plan["Shared plan<br/>[PlanSheet.tsx]"]
  node_agreement["Agreement"]
  node_rating["Trip rating<br/>[RatingScreen.tsx]"]
end

subgraph group_driver["Driver tools"]
  node_driverhome["Driver availability"]
  node_tips["Voice tip recorder"]
end

subgraph group_webcore["Web app runtime"]
  node_app["Route application<br/>[App.tsx]"]
  node_state["App preferences<br/>[appStore.ts]"]
  node_transport["Conversation transport<br/>[transport.ts]"]
  node_mock["Mock conversation<br/>[mockGateway.ts]"]
  node_voicekey["Visitor voice key<br/>[VoiceKeySheet.tsx]"]
  node_keystore[("Session voice key<br/>[voiceKeyStore.ts]")]
end

subgraph group_speech["Speech services"]
  node_speechclient["Speech client<br/>[speech.ts]"]
  node_gateway["Speech API gateway<br/>[main.py]"]
  node_registry["Provider selection<br/>[registry.py]"]
  node_provider["Speech provider interface<br/>[base.py]"]
  node_gnani["Gnani provider<br/>[gnani.py]"]
  node_mockprovider["Mock provider<br/>[mock.py]"]
end

node_traveller(("Traveller"))
node_gnaniservice{{"Gnani speech service"}}
node_devicevoice{{"Device speech"}}

node_traveller -->|"chooses language"| node_language
node_language -->|"continues setup"| node_trip
node_trip -.->|"finds drivers"| node_drivers
node_drivers -.->|"opens profile"| node_profile
node_profile -.->|"starts chat"| node_travellerchat
node_travellerchat -.->|"sends events"| node_transport
node_driverchat -.->|"sends events"| node_transport
node_transport -->|"selects mock"| node_mock
node_transport -.->|"connects WebSocket"| node_gateway
node_travellerchat -->|"renders messages"| node_messages
node_driverchat -->|"renders messages"| node_messages
node_travellerchat -->|"renders confirmations"| node_confirm
node_driverchat -->|"renders confirmations"| node_confirm
node_travellerchat -->|"opens plan"| node_plan
node_driverchat -->|"opens plan"| node_plan
node_plan -->|"views agreement"| node_agreement
node_travellerchat -.->|"plays speech"| node_speechclient
node_driverchat -->|"plays speech"| node_speechclient
node_messages -->|"replays message"| node_speechclient
node_speechclient -.->|"falls back"| node_devicevoice
node_voicekey -->|"tests key"| node_speechclient
node_voicekey -->|"saves key"| node_keystore
node_speechclient -.->|"requests speech"| node_gateway
node_gateway -->|"builds providers"| node_registry
node_registry -->|"selects Gnani"| node_gnani
node_registry -->|"selects mock"| node_mockprovider
node_gateway -->|"invokes provider"| node_provider
node_gnani -->|"implements interface"| node_provider
node_mockprovider -->|"implements interface"| node_provider
node_gnani -.->|"calls service"| node_gnaniservice
node_app -->|"reads theme"| node_state
node_traveller -.->|"switches role"| node_driverhome
node_driverhome -.->|"opens request chat"| node_driverchat
node_driverhome -.->|"records tips"| node_tips
node_agreement -.->|"continues trip"| node_rating
node_app -->|"routes chat"| node_travellerchat
node_app -->|"routes driver chat"| node_driverchat
node_app -->|"routes driver home"| node_driverhome

click node_language "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/LanguageScreen.tsx"
click node_trip "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/TripSetupScreen.tsx"
click node_drivers "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverListScreen.tsx"
click node_profile "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverProfileScreen.tsx"
click node_travellerchat "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/ChatScreen.tsx"
click node_driverchat "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverChatScreen.tsx"
click node_messages "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/MessageBubble.tsx"
click node_confirm "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/ConfirmBanner.tsx"
click node_plan "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/PlanSheet.tsx"
click node_agreement "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/AgreementScreen.tsx"
click node_rating "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/RatingScreen.tsx"
click node_driverhome "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverHomeScreen.tsx"
click node_tips "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverTipsScreen.tsx"
click node_app "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/App.tsx"
click node_state "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/store/appStore.ts"
click node_transport "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/transport.ts"
click node_mock "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/mockGateway.ts"
click node_voicekey "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/VoiceKeySheet.tsx"
click node_keystore "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/store/voiceKeyStore.ts"
click node_speechclient "https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/speech.ts"
click node_gateway "https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/main.py"
click node_registry "https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/registry.py"
click node_provider "https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/base.py"
click node_gnani "https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/gnani.py"
click node_mockprovider "https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/mock.py"

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_language,node_trip,node_drivers,node_profile toneBlue
class node_travellerchat,node_driverchat,node_messages,node_confirm,node_plan,node_agreement,node_rating toneAmber
class node_driverhome,node_tips toneMint
class node_app,node_state,node_transport,node_mock,node_voicekey,node_keystore toneRose
class node_speechclient,node_gateway,node_registry,node_provider,node_gnani,node_mockprovider,node_traveller,node_gnaniservice,node_devicevoice toneIndigo
```

## Components

### Trip setup and driver discovery

- [Language setup](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/LanguageScreen.tsx): `apps/web/src/screens/LanguageScreen.tsx`
- [Trip setup](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/TripSetupScreen.tsx): `apps/web/src/screens/TripSetupScreen.tsx`
- [Driver discovery](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverListScreen.tsx): `apps/web/src/screens/DriverListScreen.tsx`
- [Driver profile](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverProfileScreen.tsx): `apps/web/src/screens/DriverProfileScreen.tsx`

### Conversation and agreement

- [Traveller chat](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/ChatScreen.tsx): `apps/web/src/screens/ChatScreen.tsx`
- [Driver chat](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverChatScreen.tsx): `apps/web/src/screens/DriverChatScreen.tsx`
- [Translated messages](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/MessageBubble.tsx): `apps/web/src/components/chat/MessageBubble.tsx`
- [Commitment confirmations](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/ConfirmBanner.tsx): `apps/web/src/components/chat/ConfirmBanner.tsx`
- [Shared plan](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/chat/PlanSheet.tsx): `apps/web/src/components/chat/PlanSheet.tsx`
- [Agreement](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/AgreementScreen.tsx): `apps/web/src/screens/AgreementScreen.tsx`
- [Trip rating](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/RatingScreen.tsx): `apps/web/src/screens/RatingScreen.tsx`

### Driver tools

- [Driver availability](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverHomeScreen.tsx): `apps/web/src/screens/DriverHomeScreen.tsx`
- [Voice tip recorder](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/screens/DriverTipsScreen.tsx): `apps/web/src/screens/DriverTipsScreen.tsx`

### Web app runtime

- [Route application](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [App preferences](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/store/appStore.ts): `apps/web/src/store/appStore.ts`
- [Conversation transport](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/transport.ts): `apps/web/src/lib/transport.ts`
- [Mock conversation](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/mockGateway.ts): `apps/web/src/lib/mockGateway.ts`
- [Visitor voice key](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/components/VoiceKeySheet.tsx): `apps/web/src/components/VoiceKeySheet.tsx`
- [Session voice key](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/store/voiceKeyStore.ts): `apps/web/src/store/voiceKeyStore.ts`

### Speech services

- [Speech client](https://github.com/saibabooj/voicebridge/blob/main/apps/web/src/lib/speech.ts): `apps/web/src/lib/speech.ts`
- [Speech API gateway](https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/main.py): `services/gateway/app/main.py`
- [Provider selection](https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/registry.py): `services/gateway/app/providers/registry.py`
- [Speech provider interface](https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/base.py): `services/gateway/app/providers/base.py`
- [Gnani provider](https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/gnani.py): `services/gateway/app/providers/gnani.py`
- [Mock provider](https://github.com/saibabooj/voicebridge/blob/main/services/gateway/app/providers/mock.py): `services/gateway/app/providers/mock.py`

### Other components

- **Traveller**
- **Gnani speech service**
- **Device speech**

## Connections

- Traveller → Language setup: chooses language
- Language setup → Trip setup: continues setup (evidence: `apps/web/src/App.tsx`)
- Trip setup → Driver discovery: finds drivers
- Driver discovery → Driver profile: opens profile
- Driver profile → Traveller chat: starts chat
- Traveller chat → Conversation transport: sends events (evidence: `apps/web/src/screens/ChatScreen.tsx`)
- Driver chat → Conversation transport: sends events (evidence: `apps/web/src/screens/DriverChatScreen.tsx`)
- Conversation transport → Mock conversation: selects mock (evidence: `apps/web/src/lib/transport.ts`)
- Conversation transport → Speech API gateway: connects WebSocket
- Traveller chat → Translated messages: renders messages (evidence: `apps/web/src/screens/ChatScreen.tsx`)
- Driver chat → Translated messages: renders messages (evidence: `apps/web/src/screens/DriverChatScreen.tsx`)
- Traveller chat → Commitment confirmations: renders confirmations (evidence: `apps/web/src/screens/ChatScreen.tsx`)
- Driver chat → Commitment confirmations: renders confirmations (evidence: `apps/web/src/screens/DriverChatScreen.tsx`)
- Traveller chat → Shared plan: opens plan (evidence: `apps/web/src/screens/ChatScreen.tsx`)
- Driver chat → Shared plan: opens plan (evidence: `apps/web/src/screens/DriverChatScreen.tsx`)
- Shared plan → Agreement: views agreement (evidence: `apps/web/src/components/chat/PlanSheet.tsx`)
- Traveller chat → Speech client: plays speech (evidence: `apps/web/src/screens/ChatScreen.tsx`)
- Driver chat → Speech client: plays speech (evidence: `apps/web/src/screens/DriverChatScreen.tsx`)
- Translated messages → Speech client: replays message (evidence: `apps/web/src/components/chat/MessageBubble.tsx`)
- Speech client → Device speech: falls back
- Visitor voice key → Speech client: tests key (evidence: `apps/web/src/components/VoiceKeySheet.tsx`)
- Visitor voice key → Session voice key: saves key (evidence: `apps/web/src/components/VoiceKeySheet.tsx`)
- Speech client → Speech API gateway: requests speech
- Speech API gateway → Provider selection: builds providers (evidence: `services/gateway/app/main.py`)
- Provider selection → Gnani provider: selects Gnani (evidence: `services/gateway/app/providers/registry.py`)
- Provider selection → Mock provider: selects mock (evidence: `services/gateway/app/providers/registry.py`)
- Speech API gateway → Speech provider interface: invokes provider (evidence: `services/gateway/app/main.py`)
- Gnani provider → Speech provider interface: implements interface (evidence: `services/gateway/app/providers/gnani.py`)
- Mock provider → Speech provider interface: implements interface (evidence: `services/gateway/app/providers/mock.py`)
- Gnani provider → Gnani speech service: calls service
- Route application → App preferences: reads theme (evidence: `apps/web/src/App.tsx`)
- Traveller → Driver availability: switches role
- Driver availability → Driver chat: opens request chat
- Driver availability → Voice tip recorder: records tips
- Agreement → Trip rating: continues trip
- Route application → Traveller chat: routes chat (evidence: `apps/web/src/App.tsx`)
- Route application → Driver chat: routes driver chat (evidence: `apps/web/src/App.tsx`)
- Route application → Driver availability: routes driver home (evidence: `apps/web/src/App.tsx`)