# aadhithiyan107/voxedge architecture

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

- Interactive diagram: https://gitdiagram.com/aadhithiyan107/voxedge
- Repository: https://github.com/aadhithiyan107/voxedge

## Overview

VoxEdge continuously captures microphone audio, gates and evaluates rolling windows with local keyword spotting, then starts post-detection audio streaming to optional remote ASR for transcripts. FastAPI exposes session controls and status while broadcasting live events to the React dashboard. The graph separates capture/verification, ASR, API/state contracts, and UI. Source excerpts support the principal runtime calls; training and model artifacts are excluded as development assets. README documents capabilities beyond the sampled source, so only evidenced relationships are connected.

Main entry points: [`backend/audio/stream_manager.py`](https://github.com/aadhithiyan107/voxedge/blob/main/backend/audio/stream_manager.py) (Audio Stream Manager), [`backend/asr/service.py`](https://github.com/aadhithiyan107/voxedge/blob/main/backend/asr/service.py) (Deepgram Streaming), [`backend/core/state.py`](https://github.com/aadhithiyan107/voxedge/blob/main/backend/core/state.py) (Application State), [`backend/api/routes.py`](https://github.com/aadhithiyan107/voxedge/blob/main/backend/api/routes.py) (REST Session API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audio["Audio and Detection"]
  node_stream["Audio Stream Manager<br/>[stream_manager.py]"]
  node_kws["Keyword Engine<br/>[service.py]"]
  node_kwscontract["KWS Interface<br/>[interface.py]"]
end

subgraph group_speech["Speech Recognition"]
  node_asrcontract["ASR Interface<br/>[interface.py]"]
  node_asr["Deepgram Streaming<br/>[service.py]"]
end

subgraph group_backend["Backend and Contracts"]
  node_main["FastAPI App<br/>[main.py]"]
  node_routes["REST Session API<br/>[routes.py]"]
  node_state["Application State<br/>[state.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
  node_events["Event Contracts<br/>[events.py]"]
end

subgraph group_frontend["Dashboard"]
  node_app["React Dashboard<br/>[App.jsx]"]
end

node_mic(("Microphone"))
node_deepgram["Deepgram Service"]
node_browser(("Dashboard User"))

node_mic -->|"provides audio"| node_stream
node_stream -->|"evaluates windows"| node_kws
node_stream -->|"starts stream"| node_asr
node_stream -->|"sends audio"| node_asr
node_asr -->|"streams audio"| node_deepgram
node_main -->|"starts and stops"| node_stream
node_main -->|"mounts routes"| node_routes
node_routes -->|"controls session"| node_stream
node_routes -->|"reads status"| node_state
node_main -->|"connects WebSocket"| node_state
node_stream -->|"updates state"| node_state
node_asr -->|"updates transcript"| node_state
node_state -->|"builds payloads"| node_events
node_kws -.->|"implements"| node_kwscontract
node_asr -.->|"implements"| node_asrcontract
node_browser -->|"uses dashboard"| node_app
node_app -->|"fetches status and controls"| node_routes
node_config -->|"configures capture"| node_stream
node_config -->|"configures inference"| node_kws
node_config -->|"configures provider"| node_asr

click node_stream "https://github.com/aadhithiyan107/voxedge/blob/main/backend/audio/stream_manager.py"
click node_kws "https://github.com/aadhithiyan107/voxedge/blob/main/backend/kws/service.py"
click node_kwscontract "https://github.com/aadhithiyan107/voxedge/blob/main/backend/kws/interface.py"
click node_asrcontract "https://github.com/aadhithiyan107/voxedge/blob/main/backend/asr/interface.py"
click node_asr "https://github.com/aadhithiyan107/voxedge/blob/main/backend/asr/service.py"
click node_main "https://github.com/aadhithiyan107/voxedge/blob/main/backend/main.py"
click node_routes "https://github.com/aadhithiyan107/voxedge/blob/main/backend/api/routes.py"
click node_state "https://github.com/aadhithiyan107/voxedge/blob/main/backend/core/state.py"
click node_config "https://github.com/aadhithiyan107/voxedge/blob/main/backend/core/config.py"
click node_events "https://github.com/aadhithiyan107/voxedge/blob/main/backend/schemas/events.py"
click node_app "https://github.com/aadhithiyan107/voxedge/blob/main/frontend/src/App.jsx"

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_stream,node_kws,node_kwscontract,node_browser toneBlue
class node_asrcontract,node_asr toneAmber
class node_main,node_routes,node_state,node_config,node_events toneMint
class node_app toneRose
class node_mic,node_deepgram toneIndigo
```

## Components

### Audio and Detection

- [Audio Stream Manager](https://github.com/aadhithiyan107/voxedge/blob/main/backend/audio/stream_manager.py): `backend/audio/stream_manager.py`
- [Keyword Engine](https://github.com/aadhithiyan107/voxedge/blob/main/backend/kws/service.py): `backend/kws/service.py`
- [KWS Interface](https://github.com/aadhithiyan107/voxedge/blob/main/backend/kws/interface.py): `backend/kws/interface.py`

### Speech Recognition

- [ASR Interface](https://github.com/aadhithiyan107/voxedge/blob/main/backend/asr/interface.py): `backend/asr/interface.py`
- [Deepgram Streaming](https://github.com/aadhithiyan107/voxedge/blob/main/backend/asr/service.py): `backend/asr/service.py`

### Backend and Contracts

- [FastAPI App](https://github.com/aadhithiyan107/voxedge/blob/main/backend/main.py): `backend/main.py`
- [REST Session API](https://github.com/aadhithiyan107/voxedge/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Application State](https://github.com/aadhithiyan107/voxedge/blob/main/backend/core/state.py): `backend/core/state.py`
- [Runtime Settings](https://github.com/aadhithiyan107/voxedge/blob/main/backend/core/config.py): `backend/core/config.py`
- [Event Contracts](https://github.com/aadhithiyan107/voxedge/blob/main/backend/schemas/events.py): `backend/schemas/events.py`

### Dashboard

- [React Dashboard](https://github.com/aadhithiyan107/voxedge/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Other components

- **Microphone**
- **Deepgram Service**
- **Dashboard User**

## Connections

- Microphone → Audio Stream Manager: provides audio (evidence: `README.md`)
- Audio Stream Manager → Keyword Engine: evaluates windows (evidence: `backend/audio/stream_manager.py`)
- Audio Stream Manager → Deepgram Streaming: starts stream (evidence: `backend/audio/stream_manager.py`)
- Audio Stream Manager → Deepgram Streaming: sends audio (evidence: `backend/audio/stream_manager.py`)
- Deepgram Streaming → Deepgram Service: streams audio (evidence: `README.md`)
- FastAPI App → Audio Stream Manager: starts and stops (evidence: `backend/main.py`)
- FastAPI App → REST Session API: mounts routes (evidence: `backend/main.py`)
- REST Session API → Audio Stream Manager: controls session (evidence: `backend/api/routes.py`)
- REST Session API → Application State: reads status (evidence: `backend/api/routes.py`)
- FastAPI App → Application State: connects WebSocket (evidence: `backend/main.py`)
- Audio Stream Manager → Application State: updates state (evidence: `backend/audio/stream_manager.py`)
- Deepgram Streaming → Application State: updates transcript (evidence: `backend/asr/service.py`)
- Application State → Event Contracts: builds payloads (evidence: `backend/core/state.py`)
- Keyword Engine → KWS Interface: implements (evidence: `backend/kws/service.py`)
- Deepgram Streaming → ASR Interface: implements (evidence: `backend/asr/service.py`)
- Dashboard User → React Dashboard: uses dashboard (evidence: `README.md`)
- React Dashboard → REST Session API: fetches status and controls (evidence: `frontend/src/App.jsx`)
- Runtime Settings → Audio Stream Manager: configures capture (evidence: `backend/audio/stream_manager.py`)
- Runtime Settings → Keyword Engine: configures inference (evidence: `backend/kws/service.py`)
- Runtime Settings → Deepgram Streaming: configures provider (evidence: `backend/asr/service.py`)
