# bmondal98/voicescout architecture

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

- Interactive diagram: https://gitdiagram.com/bmondal98/voicescout
- Repository: https://github.com/bmondal98/voicescout

## Overview

VocalScout is a multilingual video-question answering dashboard: users choose a video and language, ask by voice or typed fallback, then receive an answer tied to a video quote and timestamp. The documented experience also includes catalog switching, video submission/indexing, and demo-mode responses. The frontend and AWS-style backend excerpts show parts of these flows, but do not establish every deployed API connection; uncertain wiring is omitted, and the indexing and retrieval stages are represented only where supported by the README or sampled source.

Main entry points: [`src/components/VoiceAssistantPanel.tsx`](https://github.com/bmondal98/voicescout/blob/main/src/components/VoiceAssistantPanel.tsx) (Voice and text panel), [`src/App.tsx`](https://github.com/bmondal98/voicescout/blob/main/src/App.tsx) (Dashboard), [`backend/chat_with_agent/lambda.py`](https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/lambda.py) (Chat handler), [`backend/chat_with_agent/common.py`](https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/common.py) (RAG and translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Video experience"]
  node_app["Dashboard<br/>[App.tsx]"]
  node_header["Language and mode<br/>[Header.tsx]"]
  node_catalog["Video catalog<br/>[videoService.ts]"]
  node_player["YouTube player"]
end

subgraph group_query["Question answering"]
  node_assistant["Voice and text panel"]
  node_recorder["Microphone capture"]
  node_speech["Audio transcription<br/>[assemblyAI.ts]"]
  node_api["Backend API client<br/>[api.ts]"]
  node_demo["Demo responses<br/>[sampleVideos.ts]"]
end

subgraph group_ingestion["Video ingestion"]
  node_videoadd["Video submission<br/>[lambda_function.py]"]
  node_indexhandler["Index dispatch<br/>[lambda_function.py]"]
  node_videoquery["Video catalog API<br/>[lambda_function.py]"]
end

subgraph group_backend["Backend services"]
  node_chat["Chat handler<br/>[lambda.py]"]
  node_agent["RAG and translation<br/>[common.py]"]
  node_vectors["Video vector index<br/>[index.py]"]
  node_embedcommon["Transcription and embedding<br/>[common.py]"]
  node_addchat["Chat record<br/>[lambda.py]"]
end

node_user(("Viewer"))
node_external{{"External services"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_header
node_app -->|"renders"| node_player
node_app -->|"renders"| node_assistant
node_app -->|"loads catalog"| node_catalog
node_catalog -->|"requests videos"| node_videoquery
node_assistant -->|"captures audio"| node_recorder
node_assistant -->|"transcribes audio"| node_speech
node_assistant -->|"submits questions"| node_api
node_assistant -.->|"uses mock answers"| node_demo
node_api -.->|"routes query"| node_chat
node_chat -->|"runs answering"| node_agent
node_chat -.->|"records query"| node_addchat
node_agent -->|"retrieves context"| node_vectors
node_agent -.->|"uses model and vector services"| node_external
node_assistant -->|"seeks to answer time"| node_player
node_videoadd -.->|"submits video"| node_indexhandler
node_indexhandler -.->|"dispatches indexing"| node_vectors
node_vectors -->|"transcribes and embeds"| node_embedcommon
node_embedcommon -.->|"uses storage and speech services"| node_external
node_videoadd -.->|"uploads media"| node_external

click node_app "https://github.com/bmondal98/voicescout/blob/main/src/App.tsx"
click node_header "https://github.com/bmondal98/voicescout/blob/main/src/components/Header.tsx"
click node_catalog "https://github.com/bmondal98/voicescout/blob/main/src/services/videoService.ts"
click node_player "https://github.com/bmondal98/voicescout/blob/main/src/components/VideoPlayerStage.tsx"
click node_assistant "https://github.com/bmondal98/voicescout/blob/main/src/components/VoiceAssistantPanel.tsx"
click node_recorder "https://github.com/bmondal98/voicescout/blob/main/src/hooks/useVoiceRecorder.ts"
click node_speech "https://github.com/bmondal98/voicescout/blob/main/src/services/assemblyAI.ts"
click node_api "https://github.com/bmondal98/voicescout/blob/main/src/services/api.ts"
click node_demo "https://github.com/bmondal98/voicescout/blob/main/src/data/sampleVideos.ts"
click node_chat "https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/lambda.py"
click node_agent "https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/common.py"
click node_vectors "https://github.com/bmondal98/voicescout/blob/main/backend/vectorembedder/index.py"
click node_embedcommon "https://github.com/bmondal98/voicescout/blob/main/backend/vectorembedder/common.py"
click node_addchat "https://github.com/bmondal98/voicescout/blob/main/backend/add-chat-entry/lambda.py"
click node_videoadd "https://github.com/bmondal98/voicescout/blob/main/backend/add-video-entry/lambda_function.py"
click node_indexhandler "https://github.com/bmondal98/voicescout/blob/main/backend/index-video-handler/lambda_function.py"
click node_videoquery "https://github.com/bmondal98/voicescout/blob/main/backend/get-videos/lambda_function.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_app,node_header,node_catalog,node_player,node_user toneBlue
class node_assistant,node_recorder,node_speech,node_api,node_demo toneAmber
class node_videoadd,node_indexhandler,node_videoquery toneMint
class node_chat,node_agent,node_vectors,node_embedcommon,node_addchat toneRose
class node_external toneIndigo
```

## Components

### Video experience

- [Dashboard](https://github.com/bmondal98/voicescout/blob/main/src/App.tsx): `src/App.tsx`
- [Language and mode](https://github.com/bmondal98/voicescout/blob/main/src/components/Header.tsx): `src/components/Header.tsx`
- [Video catalog](https://github.com/bmondal98/voicescout/blob/main/src/services/videoService.ts): `src/services/videoService.ts`
- [YouTube player](https://github.com/bmondal98/voicescout/blob/main/src/components/VideoPlayerStage.tsx): `src/components/VideoPlayerStage.tsx`

### Question answering

- [Voice and text panel](https://github.com/bmondal98/voicescout/blob/main/src/components/VoiceAssistantPanel.tsx): `src/components/VoiceAssistantPanel.tsx`
- [Microphone capture](https://github.com/bmondal98/voicescout/blob/main/src/hooks/useVoiceRecorder.ts): `src/hooks/useVoiceRecorder.ts`
- [Audio transcription](https://github.com/bmondal98/voicescout/blob/main/src/services/assemblyAI.ts): `src/services/assemblyAI.ts`
- [Backend API client](https://github.com/bmondal98/voicescout/blob/main/src/services/api.ts): `src/services/api.ts`
- [Demo responses](https://github.com/bmondal98/voicescout/blob/main/src/data/sampleVideos.ts): `src/data/sampleVideos.ts`

### Video ingestion

- [Video submission](https://github.com/bmondal98/voicescout/blob/main/backend/add-video-entry/lambda_function.py): `backend/add-video-entry/lambda_function.py`
- [Index dispatch](https://github.com/bmondal98/voicescout/blob/main/backend/index-video-handler/lambda_function.py): `backend/index-video-handler/lambda_function.py`
- [Video catalog API](https://github.com/bmondal98/voicescout/blob/main/backend/get-videos/lambda_function.py): `backend/get-videos/lambda_function.py`

### Backend services

- [Chat handler](https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/lambda.py): `backend/chat_with_agent/lambda.py`
- [RAG and translation](https://github.com/bmondal98/voicescout/blob/main/backend/chat_with_agent/common.py): `backend/chat_with_agent/common.py`
- [Video vector index](https://github.com/bmondal98/voicescout/blob/main/backend/vectorembedder/index.py): `backend/vectorembedder/index.py`
- [Transcription and embedding](https://github.com/bmondal98/voicescout/blob/main/backend/vectorembedder/common.py): `backend/vectorembedder/common.py`
- [Chat record](https://github.com/bmondal98/voicescout/blob/main/backend/add-chat-entry/lambda.py): `backend/add-chat-entry/lambda.py`

### Other components

- **Viewer**
- **External services**

## Connections

- Viewer → Dashboard: uses
- Dashboard → Language and mode: renders
- Dashboard → YouTube player: renders
- Dashboard → Voice and text panel: renders
- Dashboard → Video catalog: loads catalog
- Video catalog → Video catalog API: requests videos
- Voice and text panel → Microphone capture: captures audio
- Voice and text panel → Audio transcription: transcribes audio
- Voice and text panel → Backend API client: submits questions
- Voice and text panel → Demo responses: uses mock answers
- Backend API client → Chat handler: routes query
- Chat handler → RAG and translation: runs answering
- Chat handler → Chat record: records query
- RAG and translation → Video vector index: retrieves context
- RAG and translation → External services: uses model and vector services
- Voice and text panel → YouTube player: seeks to answer time
- Video submission → Index dispatch: submits video
- Index dispatch → Video vector index: dispatches indexing
- Video vector index → Transcription and embedding: transcribes and embeds
- Transcription and embedding → External services: uses storage and speech services
- Video submission → External services: uploads media