voicebox/docs/developer/architecture.mdx

---
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

```
app/src/
├── components/       # React components
│   ├── profiles/    # Voice profile UI
│   ├── generation/  # Speech generation UI
│   ├── stories/     # Timeline editor
│   └── shared/      # Reusable components
├── lib/             # Utilities
│   ├── api/         # Generated API client
│   └── utils/       # Helper functions
├── hooks/           # React hooks
└── stores/          # Zustand state stores
```

### 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

```python
# main.py - API routes
@app.post("/generate")
async def generate_speech(request: GenerateRequest):
    # 1. Validate request
    # 2. Load voice profile
    # 3. Generate audio with TTS
    # 4. Save to database
    # 5. Return response
```

### 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

```rust
// Sidecar process management
// File system access
// Native integrations
```

### 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
# 1. Build server binary (PyInstaller)
./scripts/build-server.sh

# 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

<CardGroup cols={2}>
  <Card title="Development Setup" icon="code" href="/development/setup">
    Set up your dev environment
  </Card>
  <Card title="Contributing" icon="code-pull-request" href="/development/contributing">
    Contribute to Voicebox
  </Card>
</CardGroup>