# dsa/fast-voice-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/dsa/fast-voice-assistant
- Repository: https://github.com/dsa/fast-voice-assistant

## Overview

1. This repository is a minimal Python agent, not a full multi-service application. The entire runtime is centered around a single entrypoint, `main.py`, plus environment-based configuration in `.env`.

2. The core process is an AI voice assistant that connects to a LiveKit room as an agent. LiveKit is the transport layer for realtime audio between a human client and the agent.

3. The data path is straightforward:
   - user microphone audio enters LiveKit,
   - the agent sends audio to Deepgram for speech-to-text,
   - the transcript is sent to Cerebras for language-model inference,
   - the response is converted to speech by Cartesia,
   - synthesized audio is streamed back through LiveKit to the client.

4. The repository’s main architectural boundary is between the local Python agent and the external SaaS services it orchestrates. The local code is mostly glue logic; the “heavy lifting” is delegated to LiveKit, Deepgram, Cerebras, and Cartesia.

5. The repo includes only the essentials needed to run the agent:
   - `main.py` as the executable entrypoint,
   - `requirements.txt` for Python dependencies,
   - `.env.example` for credentials and runtime settings,
   - `README.md` for setup and client connection instructions.

6. Configuration is environment-driven. The `.env` file is the place where API keys and LiveKit project settings are supplied, which means the agent can be deployed or run locally without changing code.

7. Runtime behavior is developer-oriented and local-first. The README shows a `python main.py dev` launch mode, indicating the agent can be started directly from the command line for interactive development rather than through a larger deployment stack.

8. Client interaction is external to this repo. The README points to the LiveKit playground as the client surface; the assistant itself does not include a custom UI. The client’s only job is to join the same LiveKit project/room so it can exchange audio with the agent.

9. The main functional subsystem is the conversational loop: audio input, transcription, model inference, and audio output. There are no separate persistence, job queue, database, or analytics subsystems visible in the repository structure.

10. For an architecture diagram, the key nodes are:
   - Human user / browser client
   - LiveKit transport
   - Python agent process (`main.py`)
   - Deepgram STT
   - Cerebras LLM
   - Cartesia TTS
   - Environment config / secrets

11. The strongest dependency relationships are linear and realtime: LiveKit is the communication backbone, while STT, LLM, and TTS are sequential processing stages in the assistant pipeline. This repo is intentionally small because the architecture is mostly service composition rather than internal code complexity.

Main entry points: [`main.py`](https://github.com/dsa/fast-voice-assistant/blob/main/main.py) (main.py), [`.env.example`](https://github.com/dsa/fast-voice-assistant/blob/main/.env.example) (Env config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local repo"]
  node_agent["main.py<br/>python agent<br/>[main.py]"]
  node_env_config["Env config<br/>secrets/config<br/>[.env.example]"]
end

subgraph group_external["External services"]
  node_livekit[("LiveKit<br/>realtime transport")]
  node_deepgram(("Deepgram<br/>speech-to-text"))
  node_cerebras(("Cerebras<br/>llm inference"))
  node_cartesia(("Cartesia<br/>text-to-speech"))
end

subgraph group_client["Client side"]
  node_human_client(("Client"))
end

node_human_client -->|"mic audio"| node_livekit
node_livekit -->|"room audio"| node_agent
node_agent -->|"transcribe"| node_deepgram
node_deepgram -->|"transcript"| node_agent
node_agent -->|"prompt"| node_cerebras
node_cerebras -->|"response text"| node_agent
node_agent -->|"speak"| node_cartesia
node_cartesia -->|"audio"| node_agent
node_agent -->|"playback"| node_livekit
node_env_config -.->|"runtime settings"| node_agent
node_human_client -.->|"conversation"| node_agent

click node_agent "https://github.com/dsa/fast-voice-assistant/blob/main/main.py"
click node_env_config "https://github.com/dsa/fast-voice-assistant/blob/main/.env.example"

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_agent,node_env_config toneBlue
class node_livekit,node_deepgram,node_cerebras,node_cartesia toneAmber
class node_human_client toneMint
```

## Components

### Local repo

Python agent and configuration in this repository.

- [main.py](https://github.com/dsa/fast-voice-assistant/blob/main/main.py): python agent · Single entrypoint for the local voice-assistant runtime and orchestration logic. · `main.py`
- [Env config](https://github.com/dsa/fast-voice-assistant/blob/main/.env.example): secrets/config · Environment-driven API keys and runtime settings supplied via .env files. · `.env.example`

### External services

SaaS systems the agent orchestrates at runtime.

- **LiveKit**: realtime transport · Audio transport layer connecting the client and the agent in a room.
- **Deepgram**: speech-to-text · Converts incoming audio into text transcripts.
- **Cerebras**: llm inference · Generates assistant responses from the transcript and conversation context.
- **Cartesia**: text-to-speech · Synthesizes spoken audio from the model response.

### Client side

Human-facing audio client outside the repo.

- **Client**: browser voice client · Human user or browser-based client that joins the LiveKit room and exchanges audio.

## Connections

- Client → LiveKit: mic audio · User audio enters the realtime room through LiveKit.
- LiveKit → main.py: room audio · The local agent connects to the LiveKit room as a participant.
- main.py → Deepgram: transcribe · Incoming audio is sent for speech-to-text.
- Deepgram → main.py: transcript · Transcribed text returns to the agent.
- main.py → Cerebras: prompt · Transcript and context are forwarded for language-model inference.
- Cerebras → main.py: response text · Generated assistant text returns to the agent.
- main.py → Cartesia: speak · Assistant text is sent for speech synthesis.
- Cartesia → main.py: audio · Synthesized speech audio returns to the agent.
- main.py → LiveKit: playback · Synthesized audio is streamed back through LiveKit.
- Env config → main.py: runtime settings · Credentials and project settings configure the agent at startup.
- Client → main.py: conversation · End-to-end interaction is mediated by the agent runtime.
