docs/MOBILE_ARCHITECTURE.md

VoiceForge Mobile App Architecture

Overview

The VoiceForge Mobile Companion App is built using Flutter to provide a cross-platform (Android/iOS) experience. It connects to the VoiceForge FastAPI backend to provide speech-to-text and text-to-speech capabilities on the go.

Tech Stack

• Framework: Flutter (Dart)
• State Management: flutter_riverpod (Recommended for scalability) or Provider
• Networking: Dio (advanced HTTP client) + web_socket_channel
• Audio: flutter_sound or record (recording), audioplayers (playback)
• Local Storage: shared_preferences (settings), hive (offline cache - optional)

Project Structure

We follow a Clean Architecture inspired feature-first approach:

lib/
├── core/                   # Global core functionality
│   ├── config/             # Environment config
│   ├── constants/          # UI constants, API endpoints
│   ├── theme/              # App theme & styles
│   ├── utils/              # Helper functions
│   └── network/            # Dio client, Interceptors
│
├── features/               # Feature-based modules
│   ├── auth/               # Authentication (if re-enabled)
│   ├── transcription/      # STT Feature
│   │   ├── data/           # Repositories, DTOs
│   │   ├── domain/         # Models, Entities
│   │   └── presentation/   # Screens, Widgets, Providers
│   ├── synthesis/          # TTS Feature
│   └── history/            # Transcripts List & Details
│
├── shared/                 # Shared widgets & models
│   ├── widgets/            # Common UI components
│   └── models/             # Shared data models
│
└── main.dart               # Entry point

API Integration

Base URL

• Development: http://<your-local-ip>:8000 (Physical Device) or http://10.0.2.2:8000 (Android Emulator)
• Production: https://api.voiceforge.com

Endpoints

Feature	Method	Endpoint	Description
STT	POST	/api/v1/stt/transcribe	Upload audio for transcription
TTS	POST	/api/v1/tts/synthesize	Convert text to speech
History	GET	/api/v1/transcripts	List past transcripts
Stream	MAX	/api/v1/ws/transcription	Real-time WebSocket stream

Real-time Transcription (WebSocket)

Flow:

1. Connect to ws://<host>/api/v1/ws/transcription?client_id=<uuid>
2. Send Audio Chunks (binary) or JSON commands.
3. Receive JSON updates: {"status": "processing", "partial": "..."}.

Design Guidelines

• Visuals: Match the "Premium Dark Theme" of the web app.
• Colors:
  • Primary: HSL(220, 14%, 96%) (Light text) / HSL(222, 47%, 11%) (Background) - Sync with web CSS
  • Accents: Vibrant gradients for action buttons.
• Typography: Inter / Roboto.

Development Workflow

1. Setup: Ensure Backend is running (docker-compose up).
2. Run: flutter run
3. Build: flutter build apk --release