# b25cs1051-kush/assembly_ai_hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/b25cs1051-kush/assembly_ai_hackathon
- Repository: https://github.com/b25cs1051-kush/assembly_ai_hackathon

## Overview

VoiceCart AI is a voice-controlled shopping storefront. A shopper speaks to the browser agent, which calls client-side tools to search and show products, compare options, answer from catalog reviews, update the cart, and conduct a confirmation-based checkout; the page reflects those actions. The browser streams audio directly to AssemblyAI, while the FastAPI server supplies catalog data and mints temporary voice tokens. Visit memory and cart behavior are client-side. The graph follows the README and sampled sources; unsampled tool handlers and UI wiring are represented only where documented, without inferring their internal calls.

Main entry points: [`backend/main.py`](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/main.py) (Store API), [`frontend/js/voice_agent.js`](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/voice_agent.js) (Voice session), [`frontend/js/app.js`](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/app.js) (Storefront state), [`backend/services/product_service.py`](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/services/product_service.py) (Product queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Shopping browser"]
  node_app["Storefront state<br/>[app.js]"]
  node_renderer["Page renderer<br/>[ui_renderer.js]"]
  node_voice_agent["Voice session<br/>[voice_agent.js]"]
  node_tools["Shopping tools<br/>[agent_tools.js]"]
  node_mic["Mic processing<br/>[mic_worklet.js]"]
  node_playback["Audio playback"]
  node_ack_clips["Voice acknowledgements<br/>[acks.json]"]
end

subgraph group_server["Catalog server"]
  node_api["Store API<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_catalog["Product catalog"]
  node_product_service["Product queries<br/>[product_service.py]"]
  node_product_data["Product dataset<br/>[products.json]"]
end

subgraph group_voice_service["Voice service"]
  node_assembly["AssemblyAI agent"]
end

node_shopper(("Shopper"))

node_shopper -->|"browses"| node_app
node_shopper -->|"speaks"| node_voice_agent
node_app -->|"requests catalog"| node_api
node_api -->|"queries"| node_product_service
node_product_service -->|"reads"| node_product_data
node_product_service -->|"returns products"| node_api
node_api -->|"returns catalog"| node_app
node_app -->|"renders state"| node_renderer
node_tools -->|"changes shopping state"| node_app
node_app -->|"requests comparison"| node_api
node_api -->|"builds comparison"| node_product_service
node_voice_agent -->|"dispatches calls"| node_tools
node_voice_agent -->|"requests token"| node_api
node_api -->|"reads credentials"| node_config
node_api -->|"mints token"| node_assembly
node_voice_agent -->|"streams mic audio"| node_assembly
node_assembly -->|"sends events and audio"| node_voice_agent
node_voice_agent -->|"processes microphone"| node_mic
node_voice_agent -->|"queues reply audio"| node_playback
node_voice_agent -->|"loads clips"| node_ack_clips

click node_app "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/app.js"
click node_renderer "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/ui_renderer.js"
click node_voice_agent "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/voice_agent.js"
click node_tools "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/agent_tools.js"
click node_mic "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/mic_worklet.js"
click node_playback "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/playback_worklet.js"
click node_ack_clips "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/audio/acks.json"
click node_api "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/main.py"
click node_config "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/config.py"
click node_product_service "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/services/product_service.py"
click node_product_data "https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/data/products.json"

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_renderer,node_voice_agent,node_tools,node_mic,node_playback,node_ack_clips toneBlue
class node_api,node_config toneAmber
class node_product_service,node_product_data toneMint
class node_assembly toneRose
class node_shopper toneIndigo
```

## Components

### Shopping browser

- [Storefront state](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Page renderer](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/ui_renderer.js): `frontend/js/ui_renderer.js`
- [Voice session](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/voice_agent.js): `frontend/js/voice_agent.js`
- [Shopping tools](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/agent_tools.js): `frontend/js/agent_tools.js`
- [Mic processing](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/mic_worklet.js): `frontend/js/mic_worklet.js`
- [Audio playback](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/js/playback_worklet.js): `frontend/js/playback_worklet.js`
- [Voice acknowledgements](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/frontend/audio/acks.json): `frontend/audio/acks.json`

### Catalog server

- [Store API](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/main.py): `backend/main.py`
- [Runtime settings](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/config.py): `backend/config.py`

### Product catalog

- [Product queries](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/backend/services/product_service.py): `backend/services/product_service.py`
- [Product dataset](https://github.com/b25cs1051-kush/assembly_ai_hackathon/blob/main/data/products.json): `data/products.json`

### Voice service

- **AssemblyAI agent**

### Other components

- **Shopper**

## Connections

- Shopper → Storefront state: browses
- Shopper → Voice session: speaks
- Storefront state → Store API: requests catalog
- Store API → Product queries: queries
- Product queries → Product dataset: reads
- Product queries → Store API: returns products
- Store API → Storefront state: returns catalog
- Storefront state → Page renderer: renders state
- Shopping tools → Storefront state: changes shopping state
- Storefront state → Store API: requests comparison
- Store API → Product queries: builds comparison
- Voice session → Shopping tools: dispatches calls
- Voice session → Store API: requests token
- Store API → Runtime settings: reads credentials
- Store API → AssemblyAI agent: mints token
- Voice session → AssemblyAI agent: streams mic audio
- AssemblyAI agent → Voice session: sends events and audio
- Voice session → Mic processing: processes microphone
- Voice session → Audio playback: queues reply audio
- Voice session → Voice acknowledgements: loads clips