---
title: "Architecture"
description: "Understanding Voicebox's technical architecture"
---

## System Overview

Voicebox uses a client-server architecture with a React frontend and Python backend. The desktop app is built with Tauri and contains two main layers:

**Frontend Layer:** A React application that handles the UI components, state management with Zustand, and data fetching with React Query (TanStack Query).

**Backend Layer:** A Python FastAPI server that provides the REST API, runs the TTS engine (Qwen3-TTS), manages the SQLite database, and handles audio processing.

These two layers communicate via HTTP, with the frontend making API requests to the backend.

## Frontend Architecture

### Tech Stack

- **Framework**: React 18 with TypeScript
- **State Management**: Zustand stores
- **Data Fetching**: React Query (TanStack Query)
- **Styling**: Tailwind CSS
- **Audio**: WaveSurfer.js
- **Desktop**: Tauri (Rust)

### Component Structure

<Files>
  <Folder name="app/src" defaultOpen>
    <Folder name="components">
      <File name="profiles/" />
      <File name="generation/" />
      <File name="stories/" />
      <File name="shared/" />
    </Folder>
    <Folder name="lib">
      <File name="api/" />
      <File name="utils/" />
    </Folder>
    <Folder name="hooks" />
    <Folder name="stores" />
  </Folder>
</Files>

### State Management

```typescript
// Example: Profile store
const useProfileStore = create((set) => ({
  profiles: [],
  selectedProfile: null,
  setProfiles: (profiles) => set({ profiles }),
  selectProfile: (id) => set({ selectedProfile: id })
}))
```

## Backend Architecture

### Tech Stack

- **Framework**: FastAPI (Python 3.11+)
- **TTS Model**: Qwen3-TTS
- **Transcription**: Whisper
- **Database**: SQLite
- **Audio**: librosa, soundfile

### API Structure

<Files>
  <Folder name="backend" defaultOpen>
    <File name="app.py" />
    <File name="main.py" />
    <File name="config.py" />
    <File name="models.py" />
    <File name="server.py" />
    <Folder name="routes">
      <File name="profiles.py" />
      <File name="generate.py" />
      <File name="history.py" />
      <File name="..." />
    </Folder>
    <Folder name="services">
      <File name="generation.py" />
      <File name="task_queue.py" />
      <File name="..." />
    </Folder>
    <Folder name="backends">
      <File name="__init__.py" />
      <File name="base.py" />
      <File name="..." />
    </Folder>
    <Folder name="database">
      <File name="models.py" />
      <File name="session.py" />
    </Folder>
    <Folder name="utils">
      <File name="audio.py" />
      <File name="effects.py" />
      <File name="..." />
    </Folder>
  </Folder>
</Files>

### Request Flow

HTTP request → **routes/** (validate input, parse params) → **services/** (business logic, orchestration) → **backends/** (TTS/STT inference) → **utils/** (audio processing)

Route handlers are intentionally thin. They validate input, delegate to a service function, and format the response. All business logic lives in `services/`.

### Key Modules

- **app.py** — FastAPI app factory, CORS, lifecycle events
- **main.py** — Entry point (imports app, runs uvicorn)
- **server.py** — Tauri sidecar launcher, parent-pid watchdog
- **services/generation.py** — Single function handling all generation modes (generate, retry, regenerate)
- **services/task_queue.py** — Serial generation queue for GPU inference
- **backends/__init__.py** — Protocol definitions and backend factory
- **backends/base.py** — Shared utilities across all engine implementations

### Backend Selection

The server detects the best inference backend at startup:

| Platform | Backend | Acceleration |
|----------|---------|-------------|
| macOS (Apple Silicon) | MLX | Metal / Neural Engine |
| Windows / Linux (NVIDIA) | PyTorch | CUDA |
| Linux (AMD) | PyTorch | ROCm |
| Intel Arc | PyTorch | IPEX / XPU |
| Windows (any GPU) | PyTorch | DirectML |
| Any | PyTorch | CPU fallback |

### Data Model

The database uses three main tables:

**Profile Table:** Stores voice profiles with fields for id, name, and language.

**Sample Table:** Stores audio samples linked to profiles via profile_id, with fields for audio_path and duration.

**Generation Table:** Stores generated audio with fields for id, profile_id, text, and audio_path.

## Desktop App (Tauri)

### Rust Backend

<Files>
  <Folder name="tauri/src-tauri" defaultOpen>
    <File name="Cargo.toml" />
    <File name="src/" />
    <Folder name="binaries" />
  </Folder>
</Files>

### Responsibilities

- Launch Python backend as sidecar process
- Native file dialogs
- System tray integration
- Auto-updates
- OS-specific features

## Build Process

### Development

```bash
# Frontend (Vite dev server)
cd app && bun run dev

# Backend (manual start)
cd backend && uvicorn main:app --reload

# Desktop app (connects to manual backend)
bun run dev
```

### Production

```bash
# Build everything (server binary + Tauri app)
bun run build

# Or build separately:
# 1. Build server binary (PyInstaller)
bun run build:server

# 2. Build Tauri app (includes server)
cd tauri && bun run tauri build
```

## Data Flow

### Generation Flow

When a user generates speech, the data flows through the following stages:

1. **User Input** - User enters text in a React component
2. **State Update** - Text is stored in Zustand state
3. **API Request** - React Query mutation triggers an API call via fetch
4. **Backend Processing** - FastAPI endpoint receives the request
5. **TTS Generation** - Qwen3-TTS model generates the audio
6. **Storage** - Audio file is saved to disk and a database record is created
7. **Response** - Backend returns the audio URL
8. **Cache Update** - React Query updates its cache with the response
9. **UI Update** - Component re-renders with new data
10. **Playback** - User can play the generated audio

## Performance Considerations

### Frontend

- **Code splitting** - Lazy load routes
- **Memoization** - React.memo for heavy components
- **Virtual scrolling** - For large lists
- **Debouncing** - Search and input handling

### Backend

- **Async operations** - All I/O is async
- **Model caching** - Keep TTS model in memory
- **Voice prompt caching** - Reuse embeddings
- **Connection pooling** - Database connections

## Security

### Current

- Local-only by default
- No authentication (localhost trust)
- File system sandboxing via Tauri

### Planned

- API key authentication
- User accounts
- Rate limiting
- HTTPS support

## Deployment Modes

### Local Mode

- Backend runs as sidecar
- All data stays on device
- No network required

### Remote Mode

- Backend on separate machine
- Frontend connects via HTTP
- Shared infrastructure possible

## Next Steps

<Cards>
  <Card title="Development Setup" href="/development/setup">
    Set up your dev environment
  </Card>
  <Card title="Contributing" href="/development/contributing">
    Contribute to Voicebox
  </Card>
</Cards>
