# gpustack/vox-box architecture

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

- Interactive diagram: https://gitdiagram.com/gpustack/vox-box
- Repository: https://github.com/gpustack/vox-box

## Overview

##### File structure
- Top-level code lives under `vox_box/`:
- `main.py` – CLI entry point
- `cmd/` – subcommands (`start`, `version`)
- `server/` – HTTP server implementation: `server.py` (launcher), `app.py` (FastAPI/Flask app), `routers.py` (route definitions), `model.py` (API data models)
- `backends/` – abstract base classes and concrete adapters for each STT/TTS engine
- `estimator/` – orchestration layer that chooses and invokes the correct backend for a request
- `downloader/` – logic to fetch and cache models from Hugging Face or ModelScope
- `config/` – configuration loader for CLI flags and environment settings
- `utils/` & `logging.py` – cross-cutting utilities (file I/O, logging, compatibility)
- `third_party/` – bundled external code for CosyVoice and Dia
- No relational or document database; persistent state is the on-disk model cache
- No separate frontend; clients are CLI and any HTTP client
- CI/build scripts in `hack/` and GitHub Actions workflows, but these are orthogonal to runtime architecture

##### README for additional insights
- Confirms REST endpoints: `/v1/audio/speech`, `/v1/audio/transcriptions`, model listing, health check
- Describes dependencies (Python ≥3.10, NVIDIA CUDA/cuDNN)
- Mentions caching models under `--data-dir`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Ingress Layer
    subgraph "Ingress (Blue)"
        direction TB
        CLI["CLI\n(vox_box/main.py)"]:::ingress
        StartCmd["Start Command\n(cmd/start.py)"]:::ingress
        VersionCmd["Version Command\n(cmd/version.py)"]:::ingress
        HTTPServerLauncher["HTTP Server Launcher\n(server/server.py)"]:::ingress
        HTTPServerLauncher -->|spawns| APIApp
        CLI -->|executes| StartCmd
        CLI -->|executes| VersionCmd
        StartCmd -->|launch| HTTPServerLauncher
    end

    %% API Layer
    subgraph "API Layer (Blue/Green)"
        direction TB
        APIApp["FastAPI App\n(server/app.py)"]:::api
        Routers["Routers\n(server/routers.py)"]:::api
        Models["API Models\n(server/model.py)"]:::api
        APIApp -->|routes requests| Routers
        Routers -->|validates via| Models
    end

    %% Core Service Layer
    subgraph "Core Service (Green)"
        direction TB
        EstimatorService["Estimator Service\n(estimator/estimate.py)"]:::service
        EstimatorBase["Estimator Base\n(estimator/base.py)"]:::service
        Downloader["Model Downloader\n(downloader/downloaders.py)"]:::service
        HubInterface["Hub Interface\n(downloader/hub.py)"]:::service
        ConfigLoader["Config Loader\n(config/config.py)"]:::service
        LoggingInt["Logging Integration\n(logging.py)"]:::service
        EstimatorService -->|uses base| EstimatorBase
        EstimatorService -->|checks cache via| Downloader
        Downloader -->|fetch via| HubInterface
        Routers -->|invokes| EstimatorService
        APIApp -->|loads config| ConfigLoader
        APIApp -->|initializes logging| LoggingInt
    end

    %% Utility Modules (Gray)
    subgraph "Utilities (Gray)"
        direction TB
        FileIO["File I/O & Paths\n(utils/file.py)"]:::util
        AudioUtil["Audio Helpers\n(utils/audio.py)"]:::util
        Compat["Import Compatibility\n(utils/compat_importlib.py)"]:::util
        ModelUtil["Model Utilities\n(utils/model.py)"]:::util
        LogHelpers["Logging Helpers\n(utils/log.py)"]:::util
        DownloadersUtil["Downloader Logic\n(downloader/downloaders.py)"]:::util
    end

    %% Backend Adapters (Orange)
    subgraph "Backend Adapters (Orange)"
        direction TB
        STTBase["STT Base Adapter\n(backends/stt/base.py)"]:::backend
        FWAdapter["Faster-Whisper Adapter\n(backends/stt/faster_whisper.py)"]:::backend
        FunASRAdapter["FunASR Adapter\n(backends/stt/funasr.py)"]:::backend
        TTSBase["TTS Base Adapter\n(backends/tts/base.py)"]:::backend
        BarkAdapter["Bark Adapter\n(backends/tts/bark.py)"]:::backend
        CosyVoiceAdapter["CosyVoice Adapter\n(backends/tts/cosyvoice.py)"]:::backend
        DiaAdapter["Dia Adapter\n(backends/tts/dia.py)"]:::backend
        EstimatorService -->|dispatches| STTBase
        EstimatorService -->|dispatches| TTSBase
        STTBase --> FWAdapter
        STTBase --> FunASRAdapter
        TTSBase --> BarkAdapter
        TTSBase --> CosyVoiceAdapter
        TTSBase --> DiaAdapter
    end

    %% Third-Party Code
    subgraph "Third-Party (Gray)"
        direction TB
        CosyVoiceLib["CosyVoice Library\n(third_party/CosyVoice)"]:::third
        DiaLib["Dia Library\n(third_party/dia)"]:::third
        CosyVoiceAdapter --> CosyVoiceLib
        DiaAdapter --> DiaLib
    end

    %% External Systems & Storage
    subgraph "External & Storage (Gray)"
        direction TB
        ModelHub["Model Hubs\n(HuggingFace/ModelScope)"]:::external
        LocalCache["Model Cache\n(Local Filesystem)"]:::externalStorage
        Downloader -->|downloads| ModelHub
        Downloader -->|stores| LocalCache
        EstimatorService -->|loads from| LocalCache
    end

    %% Request Flow
    HTTPServerLauncher -->|HTTP request| APIApp
    APIApp -->|request| Routers
    Routers -->|handler| Models
    Routers -->|calls| EstimatorService
    EstimatorService -->|inference| STTBase
    EstimatorService -->|inference| TTSBase
    EstimatorService -->|returns result| Routers
    Routers -->|response| APIApp
    APIApp -->|HTTP response| HTTPServerLauncher

    %% Click Events
    click CLI "https://github.com/gpustack/vox-box/blob/main/vox_box/main.py"
    click StartCmd "https://github.com/gpustack/vox-box/blob/main/vox_box/cmd/start.py"
    click VersionCmd "https://github.com/gpustack/vox-box/blob/main/vox_box/cmd/version.py"
    click HTTPServerLauncher "https://github.com/gpustack/vox-box/blob/main/vox_box/server/server.py"
    click APIApp "https://github.com/gpustack/vox-box/blob/main/vox_box/server/app.py"
    click Routers "https://github.com/gpustack/vox-box/blob/main/vox_box/server/routers.py"
    click Models "https://github.com/gpustack/vox-box/blob/main/vox_box/server/model.py"
    click ConfigLoader "https://github.com/gpustack/vox-box/blob/main/vox_box/config/config.py"
    click LoggingInt "https://github.com/gpustack/vox-box/blob/main/vox_box/logging.py"
    click FileIO "https://github.com/gpustack/vox-box/blob/main/vox_box/utils/file.py"
    click AudioUtil "https://github.com/gpustack/vox-box/blob/main/vox_box/utils/audio.py"
    click Compat "https://github.com/gpustack/vox-box/blob/main/vox_box/utils/compat_importlib.py"
    click ModelUtil "https://github.com/gpustack/vox-box/blob/main/vox_box/utils/model.py"
    click LogHelpers "https://github.com/gpustack/vox-box/blob/main/vox_box/utils/log.py"
    click HubInterface "https://github.com/gpustack/vox-box/blob/main/vox_box/downloader/hub.py"
    click Downloader "https://github.com/gpustack/vox-box/blob/main/vox_box/downloader/downloaders.py"
    click EstimatorService "https://github.com/gpustack/vox-box/blob/main/vox_box/estimator/estimate.py"
    click EstimatorBase "https://github.com/gpustack/vox-box/blob/main/vox_box/estimator/base.py"
    click FWAdapter "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/stt/faster_whisper.py"
    click FunASRAdapter "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/stt/funasr.py"
    click STTBase "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/stt/base.py"
    click TTSBase "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/tts/base.py"
    click BarkAdapter "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/tts/bark.py"
    click CosyVoiceAdapter "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/tts/cosyvoice.py"
    click DiaAdapter "https://github.com/gpustack/vox-box/blob/main/vox_box/backends/tts/dia.py"
    click CosyVoiceLib "https://github.com/gpustack/vox-box/tree/main/vox_box/third_party/CosyVoice"
    click DiaLib "https://github.com/gpustack/vox-box/tree/main/vox_box/third_party/dia"

    %% Styles
    classDef ingress fill:#B3CDE3,stroke:#005B96,color:#000
    classDef api fill:#6497B1,stroke:#005B96,color:#fff
    classDef service fill:#BFD8B8,stroke:#386641,color:#000
    classDef util fill:#D3D3D3,stroke:#666,color:#000
    classDef backend fill:#F4A261,stroke:#E76F51,color:#000
    classDef third fill:#CCCCCC,stroke:#888888,color:#000
    classDef external fill:#EEEEEE,stroke:#888888,color:#000,stroke-dasharray: 5 5
    classDef externalStorage fill:#DDDDDD,stroke:#888888,color:#000,stroke-dasharray: 5 5
```
