Add .npmrc for bun usage and update dependencies

- Created a new .npmrc file to enforce bun usage. - Bumped version numbers for multiple packages to 0.1.9 in bun.lock. - Added react-sound-visualizer dependency to enhance audio visualization features. - Introduced convert:assets script in package.json for asset optimization. - Updated CONTRIBUTING.md with instructions for converting assets to web formats. - Added documentation files for API endpoints and developer guidelines in the docs directory.
2026-09-18 06:10:43 -07:00 · 2026-01-29 18:56:10 -08:00
parent 462f104494
commit 7b5e73cfa8
58 changed files with 8014 additions and 106 deletions
@@ -0,0 +1,202 @@
+---
+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>