# damvolkov/e-voice architecture

> Architecture diagram of the GitHub repository damvolkov/e-voice, 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/damvolkov/e-voice
- Repository: https://github.com/damvolkov/e-voice

## Overview

e-voice is a CPU-first Rust speech-to-text service that returns streaming or file transcripts with per-segment emotion. Its main workflow accepts audio through compatible HTTP/WebSocket APIs, normalizes audio, runs configurable speech-processing stages, and emits transcript events or a completed transcript. The README documents the pipeline and protocol capabilities; excerpts show gateway routing, batch decoding, and runner selection. Several internal workflow stages are documented but unsampled, so their detailed implementation links are limited to those documented relationships.

Main entry points: [`stt/src/api/server.rs`](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/server.rs) (HTTP gateway), [`stt/src/api/batch.rs`](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/batch.rs) (File intake), [`stt/src/api/live.rs`](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/live.rs) (Live intake), [`stt/src/workflow/runner.rs`](https://github.com/damvolkov/e-voice/blob/main/stt/src/workflow/runner.rs) (Pipeline runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_server["HTTP gateway<br/>[server.rs]"]
  node_openai["OpenAI APIs"]
  node_deepgram["Deepgram API<br/>[listen.rs]"]
  node_scribe["ElevenLabs Scribe<br/>[scribe.rs]"]
  node_native["Native stream<br/>[stream.rs]"]
  node_batch["File intake<br/>[batch.rs]"]
  node_live["Live intake<br/>[live.rs]"]
end

subgraph group_workflow["Speech workflow"]
  node_audio["Audio decoding<br/>[audio.rs]"]
  node_pipeline["Configurable stages"]
  node_runner["Pipeline runner<br/>[runner.rs]"]
  node_session["Segment sessions<br/>[session.rs]"]
  node_results["Transcript events<br/>[transcript.rs]"]
end

subgraph group_runtime["Runtime and configuration"]
  node_state["Request state<br/>[state.rs]"]
  node_config["Pipeline config<br/>[pipeline.rs]"]
  node_settings["Service settings<br/>[settings.rs]"]
  node_lifecycle["Startup lifecycle<br/>[lifespan.rs]"]
end

subgraph group_clients["Audio client"]
  node_ecli["ecli commands<br/>[stt.rs]"]
  node_microphone["Microphone input<br/>[mic.rs]"]
  node_wav["WAV playback<br/>[wav.rs]"]
end

node_client(("API clients"))

node_client -->|"sends audio"| node_server
node_server -->|"routes requests"| node_openai
node_server -->|"routes requests"| node_deepgram
node_server -->|"routes requests"| node_scribe
node_server -->|"routes requests"| node_native
node_server -->|"starts service"| node_lifecycle
node_openai -->|"uses file intake"| node_batch
node_openai -->|"uses live intake"| node_live
node_deepgram -->|"uses file intake"| node_batch
node_deepgram -->|"uses live intake"| node_live
node_scribe -->|"uses file intake"| node_batch
node_native -->|"uses live intake"| node_live
node_batch -->|"decodes files"| node_audio
node_batch -->|"transcribes audio"| node_runner
node_live -->|"streams audio"| node_runner
node_runner -->|"runs stages"| node_pipeline
node_pipeline -->|"segments speech"| node_session
node_pipeline -->|"produces transcript"| node_results
node_state -->|"holds runner"| node_runner
node_settings -->|"loads pipeline options"| node_config
node_lifecycle -->|"builds shared state"| node_state
node_ecli -->|"captures audio"| node_microphone
node_ecli -->|"plays WAV input"| node_wav
node_ecli -->|"streams to gateway"| node_server

click node_server "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/server.rs"
click node_openai "https://github.com/damvolkov/e-voice/tree/main/stt/src/api/openai"
click node_deepgram "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/deepgram/listen.rs"
click node_scribe "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/elevenlabs/scribe.rs"
click node_native "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/native/stream.rs"
click node_batch "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/batch.rs"
click node_live "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/live.rs"
click node_audio "https://github.com/damvolkov/e-voice/blob/main/stt/src/core/audio.rs"
click node_pipeline "https://github.com/damvolkov/e-voice/tree/main/stt/src/workflow"
click node_runner "https://github.com/damvolkov/e-voice/blob/main/stt/src/workflow/runner.rs"
click node_session "https://github.com/damvolkov/e-voice/blob/main/stt/src/workflow/session.rs"
click node_results "https://github.com/damvolkov/e-voice/blob/main/stt/src/schema/transcript.rs"
click node_state "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/state.rs"
click node_config "https://github.com/damvolkov/e-voice/blob/main/stt/src/config/pipeline.rs"
click node_settings "https://github.com/damvolkov/e-voice/blob/main/stt/src/core/settings.rs"
click node_lifecycle "https://github.com/damvolkov/e-voice/blob/main/stt/src/api/lifespan.rs"
click node_ecli "https://github.com/damvolkov/e-voice/blob/main/cli/src/stt.rs"
click node_microphone "https://github.com/damvolkov/e-voice/blob/main/cli/src/mic.rs"
click node_wav "https://github.com/damvolkov/e-voice/blob/main/cli/src/wav.rs"

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_server,node_openai,node_deepgram,node_scribe,node_native,node_batch,node_live,node_client toneBlue
class node_audio,node_pipeline,node_runner,node_session,node_results toneAmber
class node_state,node_config,node_settings,node_lifecycle toneMint
class node_ecli,node_microphone,node_wav toneRose
```

## Components

### API gateway

- [HTTP gateway](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/server.rs): `stt/src/api/server.rs`
- [OpenAI APIs](https://github.com/damvolkov/e-voice/tree/main/stt/src/api/openai): `stt/src/api/openai`
- [Deepgram API](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/deepgram/listen.rs): `stt/src/api/deepgram/listen.rs`
- [ElevenLabs Scribe](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/elevenlabs/scribe.rs): `stt/src/api/elevenlabs/scribe.rs`
- [Native stream](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/native/stream.rs): `stt/src/api/native/stream.rs`
- [File intake](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/batch.rs): `stt/src/api/batch.rs`
- [Live intake](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/live.rs): `stt/src/api/live.rs`

### Speech workflow

- [Audio decoding](https://github.com/damvolkov/e-voice/blob/main/stt/src/core/audio.rs): `stt/src/core/audio.rs`
- [Configurable stages](https://github.com/damvolkov/e-voice/tree/main/stt/src/workflow): `stt/src/workflow`
- [Pipeline runner](https://github.com/damvolkov/e-voice/blob/main/stt/src/workflow/runner.rs): `stt/src/workflow/runner.rs`
- [Segment sessions](https://github.com/damvolkov/e-voice/blob/main/stt/src/workflow/session.rs): `stt/src/workflow/session.rs`
- [Transcript events](https://github.com/damvolkov/e-voice/blob/main/stt/src/schema/transcript.rs): `stt/src/schema/transcript.rs`

### Runtime and configuration

- [Request state](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/state.rs): `stt/src/api/state.rs`
- [Pipeline config](https://github.com/damvolkov/e-voice/blob/main/stt/src/config/pipeline.rs): `stt/src/config/pipeline.rs`
- [Service settings](https://github.com/damvolkov/e-voice/blob/main/stt/src/core/settings.rs): `stt/src/core/settings.rs`
- [Startup lifecycle](https://github.com/damvolkov/e-voice/blob/main/stt/src/api/lifespan.rs): `stt/src/api/lifespan.rs`

### Audio client

- [ecli commands](https://github.com/damvolkov/e-voice/blob/main/cli/src/stt.rs): `cli/src/stt.rs`
- [Microphone input](https://github.com/damvolkov/e-voice/blob/main/cli/src/mic.rs): `cli/src/mic.rs`
- [WAV playback](https://github.com/damvolkov/e-voice/blob/main/cli/src/wav.rs): `cli/src/wav.rs`

### Other components

- **API clients**

## Connections

- API clients → HTTP gateway: sends audio
- HTTP gateway → OpenAI APIs: routes requests (evidence: `stt/src/api/server.rs`)
- HTTP gateway → Deepgram API: routes requests (evidence: `stt/src/api/server.rs`)
- HTTP gateway → ElevenLabs Scribe: routes requests (evidence: `stt/src/api/server.rs`)
- HTTP gateway → Native stream: routes requests (evidence: `stt/src/api/server.rs`)
- HTTP gateway → Startup lifecycle: starts service (evidence: `stt/src/api/server.rs`)
- OpenAI APIs → File intake: uses file intake (evidence: `stt/src/api/openai/formats.rs`)
- OpenAI APIs → Live intake: uses live intake (evidence: `stt/src/api/openai/realtime.rs`)
- Deepgram API → File intake: uses file intake (evidence: `stt/src/api/deepgram/listen.rs`)
- Deepgram API → Live intake: uses live intake (evidence: `stt/src/api/deepgram/listen.rs`)
- ElevenLabs Scribe → File intake: uses file intake (evidence: `stt/src/api/elevenlabs/scribe.rs`)
- Native stream → Live intake: uses live intake (evidence: `stt/src/api/native/stream.rs`)
- File intake → Audio decoding: decodes files (evidence: `stt/src/api/batch.rs`)
- File intake → Pipeline runner: transcribes audio (evidence: `stt/src/api/batch.rs`)
- Live intake → Pipeline runner: streams audio (evidence: `stt/src/api/live.rs`)
- Pipeline runner → Configurable stages: runs stages
- Configurable stages → Segment sessions: segments speech (evidence: `stt/src/workflow/session.rs`)
- Configurable stages → Transcript events: produces transcript
- Request state → Pipeline runner: holds runner (evidence: `stt/src/api/state.rs`)
- Service settings → Pipeline config: loads pipeline options (evidence: `stt/src/core/settings.rs`)
- Startup lifecycle → Request state: builds shared state (evidence: `stt/src/api/state.rs`)
- ecli commands → Microphone input: captures audio (evidence: `cli/src/stt.rs`)
- ecli commands → WAV playback: plays WAV input (evidence: `cli/src/stt.rs`)
- ecli commands → HTTP gateway: streams to gateway
