System Architecture

VoiceForge is designed as a modular monolith. While it runs as a unified local application, the internal components are strictly decoupled to allow for future splitting into microservices (e.g., separating inference from the API).

High-Level Data Flow


                  [ USER BROWSER ]
                         |
                    (HTTP/JSON)
                         |
           +-------------v-------------+
           |       API GATEWAY         |  <-- FastAPI (main.py)
           |    (Request Validation)   |
           +-------------+-------------+
                         |
        +----------------+----------------+
        |                                 |
+-------v-------+                 +-------v-------+
|  SERVICE:     |                 |  SERVICE:     |
|  Voice Cloning|                 |  TTS Engine   |
+-------+-------+                 +-------+-------+
        |                                 |
  (Speaker Encoder)                (Flow Matching)
        |                                 |
        v                                 v
+-------------------------------------------------+
|               ML INFERENCE MODEL                |  <-- PyTorch / OnnxRunTime
|         (Optimized for CPU execution)           |
+-------------------------------------------------+

Frontend Layer

The UI is built with Next.js 14 (App Router) and React Server Components.

State ManagementZustand is used for global client state (e.g., the active podcast cast, audio player status).
Audio VisualizationReal-time waveforms are rendered using the Web Audio API and bespoke Canvas/Framer Motion animations.
StylingTailwind CSS v4 with a custom design system centered around "Zinc" dark mode aesthetics.

Inference Engine

The core intelligence runs on Python 3.10+ and PyTorch.

F5-TTS ArchitectureWe utilize a Flow Matching transformer model that treats speech generation as an iterative denoising process.
VocoderBigVGAN is used to convert the generated mel-spectrograms into high-fidelity audible waveforms.
CPU OptimizationModels are quantized and optimized to run reasonably fast on standard consumer CPUs, avoiding hard dependencies on CUDA.

Codebase Structure

/backend (Root)

src/
├── api/ # FastAPI Routes
├── core/ # Config & Security
├── services/ # Business Logic
└── ml/ # Model Definitions

/frontend

app/
├── docs/ # Documentation Logic
└── page.tsx # Landing Page
components/ # Reusable UI
lib/ # Utilities