# svpino/cartesia-demo architecture

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

- Interactive diagram: https://gitdiagram.com/svpino/cartesia-demo
- Repository: https://github.com/svpino/cartesia-demo

## Overview

##### Project type and purpose
- This is a Python-based “voice assistant” service that connects into a LiveKit real-time audio streaming room, processes audio via AI back-ends (OpenAI for language and Cartesia for spatial/semantic functions), and makes itself available in the hosted Agents Playground UI. It is a single “backend” service (no frontend code here) invoked via a CLI wrapper (`uv run python voice.py …`).

##### File structure
- Top level:
- voice.py – the only application entrypoint (defines commands `download-files` and `start`)
- pyproject.toml & uv.lock – Python dependency & lock files
- README.md – usage instructions & environment variables
- .gitignore/.python-version – dev files
- No separate “frontend” or “src” folders → everything is in one script, so it’s a thin orchestration layer calling external services.

##### README
- Requires environment variables for LiveKit, Cartesia, OpenAI.
- Two-phase operation:
a. `voice.py download-files` (pre-fetch assets)
b. `voice.py start` (boot into the LiveKit session as an agent)
- After starting, end users join via the hosted Agents Playground UI (in a browser) that connects to the same LiveKit room.

a. Main components
- Voice Assistant Service (voice.py)
- LiveKit Server (real-time audio/video server)
- Agents Playground UI (hosted web client)
- OpenAI API (LLM/text generation)
- Cartesia API (spatial/semantic processing)
- Local File System (downloaded assets)
b. Relationships & interactions
1. Agents Playground UI ⇄ LiveKit Server — streams audio/video to/from browser
2. Voice Assistant Service ⇄ LiveKit Server — joins the same room as a client, receives incoming audio streams and publishes responses
3. Voice Assistant Service → OpenAI API — for transcription, chat completion, or response generation
4. Voice Assistant Service → Cartesia API — for spatial/semantic enrichment or other domain-specific processing
5. Voice Assistant Service → Local File System — on `download-files` command, fetches and stores required assets
c. Architectural patterns & principles
- Single-service orchestration layer
- Event-driven / streaming interactions via WebSockets (LiveKit)
- Clear separation between real-time transport (LiveKit) and compute (OpenAI/Cartesia)
- Configuration via environment variables for secrets/URLs
d. Key technologies
- Python 3.x, CLI orchestration (`uv` CLI tool or custom wrapper)
- LiveKit (WebRTC signaling and media server)
- OpenAI REST API
- Cartesia REST API
- pyproject.toml for dependency management

##### Detailed capture of essential elements
- Environment variables grouping next to the Voice Assistant component
- A note that the Agents Playground is “hosted separately” but uses the same LiveKit room
- If desired, break out the “audio in → transcription → response generation → audio out” flow inside the Voice Assistant for a deeper view

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Internal App Tier
    subgraph "Internal App Tier"
        direction TB
        VoiceAssistant["Voice Assistant Service\n- CLI: download-files, start\n- Env vars config"]:::internal
        LocalFS["Local File System"]:::storage
    end

    %% External Media Tier
    subgraph "External Media Tier"
        direction TB
        LiveKitServer(["LiveKit Server"]):::media
    end

    %% External AI Tier
    subgraph "External AI Tier"
        direction TB
        OpenAI(["OpenAI API"]):::externalAI
        Cartesia(["Cartesia API"]):::externalAI
    end

    %% External Client Tier
    subgraph "External Client Tier"
        direction TB
        AgentsUI(["Agents Playground UI\n(hosted separately)"]):::client
    end

    %% Connections
    AgentsUI <--> LiveKitServer
    VoiceAssistant <--> LiveKitServer
    VoiceAssistant -->|REST call| OpenAI
    VoiceAssistant -->|REST call| Cartesia
    VoiceAssistant -->|stores assets| LocalFS

    %% Click Events
    click VoiceAssistant "https://github.com/svpino/cartesia-demo/blob/main/voice.py"
    click LocalFS "https://github.com/svpino/cartesia-demo/blob/main/voice.py"
    click README "https://github.com/svpino/cartesia-demo/blob/main/README.md"
    click PyProject "https://github.com/svpino/cartesia-demo/blob/main/pyproject.toml"
    click Lockfile "https://github.com/svpino/cartesia-demo/blob/main/uv.lock"
    click GitIgnore "https://github.com/svpino/cartesia-demo/blob/main/.gitignore"
    click PyVersion "https://github.com/svpino/cartesia-demo/blob/main/.python-version"

    %% Styles
    classDef internal fill:#E8F1FC,stroke:#0366D6,color:#0366D6,stroke-width:2px;
    classDef media fill:#FFF5E6,stroke:#AE5E0D,color:#AE5E0D,stroke-width:2px,stroke-dasharray: 5 5;
    classDef externalAI fill:#F0F8FF,stroke:#00008B,color:#00008B,stroke-width:2px;
    classDef client fill:#E6FFFA,stroke:#009688,color:#004D40,stroke-width:2px;
    classDef storage fill:#F5F5F5,stroke:#8B8B8B,color:#333333,stroke-width:2px;
    
    %% Legend
    subgraph "Legend"
        direction TB
        S1["Double-headed arrow: WebRTC streaming"]:::note
        S2["Single-headed arrow: REST API call"]:::note
        S3["Cylinder: Media server"]:::note
    end
    classDef note fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2, font-style:italic;
```
