Developer Quick Start

Last Updated: 2025-12-01

Welcome to VoiceAssist development! This guide will get you up and running quickly.

Prerequisites

• Node.js 20+ and pnpm 8+
• Python 3.11+ with pip
• Docker and Docker Compose
• Git for version control

Quick Setup (5 minutes)

1. Clone and Install

# Clone the repository
git clone https://github.com/your-org/VoiceAssist.git
cd VoiceAssist

# Install all dependencies
pnpm install

# Copy environment template
cp .env.example .env

2. Start Development Services

# Start backend services (API Gateway, databases)
docker-compose up -d

# Start frontend development server
pnpm dev

3. Verify Setup

• Frontend: http://localhost:5173
• API Gateway: http://localhost:8000
• API Docs: http://localhost:8000/docs

Project Structure

VoiceAssist/
├── apps/
│   ├── web-app/          # React frontend (Vite + TypeScript)
│   ├── admin-panel/      # Admin dashboard
│   └── docs-site/        # Documentation (Next.js)
├── packages/
│   ├── api-client/       # Type-safe API client
│   ├── config/           # Shared configuration
│   ├── types/            # TypeScript types
│   ├── ui/               # Shared UI components
│   └── utils/            # Shared utilities
├── services/
│   └── api-gateway/      # FastAPI backend
└── docs/                 # Documentation source

Key Documentation

Architecture

• Unified Architecture - Complete system overview
• Backend Architecture - API Gateway design
• Frontend Architecture - React app structure
• Realtime Architecture - WebSocket systems

Voice Pipeline

• Thinker-Talker Pipeline - Voice architecture (recommended)
• Voice Mode Pipeline - Voice mode overview
• Voice Pipeline WebSocket - WebSocket protocol

API Reference

• REST API Reference - Complete endpoint docs
• WebSocket Protocol - Real-time communication
• Data Model - Database schema

Development

• Development Setup - Full setup guide
• Local Development - Local environment tips
• Testing Guide - Testing strategies

Common Development Tasks

Running Tests

# Frontend tests
pnpm test

# Backend tests
cd services/api-gateway
pytest tests/ -v

# E2E tests
pnpm test:e2e

Code Quality

# Lint all packages
pnpm lint

# Type check
pnpm typecheck

# Format code
pnpm format

Building for Production

# Build all apps
pnpm build

# Build specific app
pnpm --filter web-app build

Development Workflow

Branch Naming

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring

Commit Messages

Follow conventional commits:

feat(voice): add speech interruption support
fix(api): handle null conversation IDs
docs(readme): update installation instructions

Pull Requests

1. Create feature branch from main
2. Make changes with tests
3. Run pnpm lint && pnpm test
4. Open PR with description
5. Address review feedback
6. Squash and merge

Key Services

Getting Help

• Documentation: assistdocs.asimo.io
• Architecture Questions: See UNIFIED_ARCHITECTURE.md
• API Questions: See API_REFERENCE.md

Next Steps

1. Read the Architecture Overview
2. Explore the Thinker-Talker Pipeline
3. Review the API Reference
4. Check Contributing Guide