Docs / Raw

Development Setup

Sourced from docs/DEVELOPMENT_SETUP.md

Edit on GitHub

VoiceAssist Development Setup Guide

This guide walks you through setting up your local development environment for VoiceAssist.

Table of Contents

Prerequisites

Required Software

  • Git 2.30+
  • Docker 24.0+ and Docker Compose 2.20+
  • Python 3.11+ (for backend development)
  • Node.js 18+ (for frontend development)
  • pnpm 8+ (package manager for frontend monorepo)
  • Visual Studio Code or PyCharm for IDE
  • Postman or Insomnia for API testing
  • pgAdmin or DBeaver for database management

Backend Setup

1. Clone the Repository

git clone git@github.com:mohammednazmy/VoiceAssist.git
cd VoiceAssist

2. Set Up Python Virtual Environment

cd services/api-gateway
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Backend Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

# From repo root
cp .env.example .env

Edit .env and configure the following required variables:

# Core
ENVIRONMENT=development
DEBUG=true

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=voiceassist
POSTGRES_PASSWORD=<your-password>
POSTGRES_DB=voiceassist_db
DATABASE_URL=postgresql://<user>:<password>@localhost:5432/voiceassist_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=<your-password>

# Qdrant (vector database)
QDRANT_HOST=localhost
QDRANT_PORT=6333

# Security
SECRET_KEY=<generate-with-openssl-rand-hex-32>
JWT_SECRET=<generate-with-openssl-rand-hex-32>
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# OpenAI
OPENAI_API_KEY=<your-openai-api-key>
OPENAI_MODEL=gpt-4-turbo-preview

# Nextcloud (optional for development)
NEXTCLOUD_URL=http://localhost:8080
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=<your-password>

5. Validate Environment

# From repo root
make check-env

This command validates that all required environment variables are set.

6. Start Infrastructure Services

# From repo root
docker compose up -d postgres redis qdrant

7. Run Database Migrations

cd services/api-gateway
source venv/bin/activate
alembic upgrade head

Frontend Setup

1. Install pnpm

If you don't have pnpm installed:

npm install -g pnpm

Or see pnpm installation docs for alternative methods.

2. Install Frontend Dependencies

# From repo root
pnpm install

This installs dependencies for all packages in the monorepo (apps and shared packages).

3. Build Shared Packages

pnpm build

This builds all shared packages that other apps depend on.

4. Start Development Server

# Start all apps in dev mode
pnpm dev

# Or start specific apps
cd apps/web-app
pnpm dev

cd apps/admin-panel
pnpm dev

Frontend Project Structure

VoiceAssist/
├── apps/
│   ├── admin-panel/       # Admin dashboard (React + Vite)
│   └── web-app/           # Main web application (React + Vite)
├── packages/
│   ├── api-client/        # API client library
│   ├── config/            # Shared configuration
│   ├── design-tokens/     # Design system tokens
│   ├── types/             # TypeScript types
│   ├── ui/                # Shared UI components
│   └── utils/             # Shared utilities
└── pnpm-workspace.yaml    # pnpm workspace config

Development Tooling

Makefile Targets

The repo includes a Makefile with common development tasks:

# Environment
make check-env          # Validate environment variables
make check-openai       # Verify OpenAI API key is valid
make install            # Install all dependencies

# Development
make dev                # Start all services with Docker Compose
make stop               # Stop all Docker Compose services
make logs               # View Docker Compose logs

# Testing
make test               # Run all backend tests
make test-unit          # Run backend unit tests only
make test-frontend      # Run frontend tests

# Quality Checks
make lint               # Run Python and frontend linters
make type-check         # Run Python and TypeScript type checking
make bandit             # Run Bandit security scanner
make security           # Run all security scans
make pre-commit         # Run pre-commit hooks on all files

# Cleanup
make clean              # Remove build artifacts and caches

Pre-commit Hooks

We use pre-commit hooks to enforce code quality standards.

Install pre-commit

cd services/api-gateway
source venv/bin/activate
pip install pre-commit

Setup hooks

# From repo root
pre-commit install

This installs git hooks that run automatically before each commit.

Manual Run

# Run on all files
pre-commit run --all-files

# Run on staged files only
pre-commit run

What Pre-commit Checks

  • Black - Python code formatting
  • isort - Python import sorting
  • flake8 - Python linting
  • mypy - Python type checking (optional)
  • Bandit - Python security scanning
  • Prettier - Frontend code formatting
  • ESLint - TypeScript/JavaScript linting
  • shellcheck - Shell script linting
  • hadolint - Dockerfile linting

Running the Application

# Start all services (backend + frontend + infrastructure)
docker compose up -d

# View logs
docker compose logs -f api-gateway

Access the application:

Backend Only

cd services/api-gateway
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Only

# Start specific frontend app
cd apps/web-app
pnpm dev

# Or
cd apps/admin-panel
pnpm dev

Verifying OpenAI API Key Integration

The application requires a valid OpenAI API key for LLM features (chat, RAG, voice mode).

Quick Verification

# From repo root (uses venv and settings automatically)
make check-openai

This runs a verification script that:

  1. Loads the OPENAI_API_KEY from .env via Pydantic Settings
  2. Validates the key format (should start with sk-)
  3. Makes a live API call to OpenAI (lists available models)
  4. Reports success or failure with actionable error messages

Manual Script Usage

# From repo root
cd services/api-gateway
source venv/bin/activate
python ../../scripts/check_openai_key.py

# With verbose output
python ../../scripts/check_openai_key.py --verbose

# Skip live API test (only validate config)
python ../../scripts/check_openai_key.py --skip-api-test

Health Check Endpoint

When the backend is running, you can also verify OpenAI connectivity via:

curl http://localhost:8000/health/openai

Returns:

  • 200 OK - Key is valid and API is accessible
  • 503 Service Unavailable - Key not configured or API not accessible

Example response:

{
  "status": "ok",
  "configured": true,
  "accessible": true,
  "latency_ms": 245.67,
  "models_accessible": 108,
  "timestamp": 1732476123.456
}

Live Integration Tests

For deeper validation, run the live OpenAI integration tests:

cd services/api-gateway
source venv/bin/activate
export PYTHONPATH=.
export LIVE_OPENAI_TESTS=1
pytest tests/integration/test_openai_config.py -v

These tests verify:

  • API key can list models
  • LLM client can generate completions
  • Realtime Voice service is properly configured

Note: Live tests are skipped by default to avoid API costs. Enable with LIVE_OPENAI_TESTS=1.

Troubleshooting

If verification fails:

  1. Key not configured: Check .env file has OPENAI_API_KEY=sk-...
  2. Invalid format: Ensure key starts with sk- and is 40+ characters
  3. API rejected: Verify key at https://platform.openai.com/api-keys
  4. Rate limited: Check your OpenAI account usage and billing
  5. Network error: Verify server can reach api.openai.com

Testing

Backend Tests

# From repo root
make test              # All tests
make test-unit         # Unit tests only

# Or directly with pytest
cd services/api-gateway
source venv/bin/activate
pytest                 # All tests
pytest tests/unit/     # Unit tests
pytest tests/e2e/      # E2E tests
pytest -v -k "test_auth"  # Specific tests

Frontend Tests

# From repo root
pnpm test

# Or in specific package
cd apps/web-app
pnpm test

Test Coverage

# Backend coverage
cd services/api-gateway
source venv/bin/activate
pytest --cov=app --cov-report=html

# View coverage report
open htmlcov/index.html

Linting and Type Checking

Backend

# From repo root
make lint              # Flake8 + Black + isort
make type-check        # mypy type checking

# Or manually
cd services/api-gateway
source venv/bin/activate
black app/
isort app/
flake8 app/
mypy app/

Frontend

# From repo root
pnpm lint              # ESLint
pnpm type-check        # TypeScript compiler

# Or in specific package
cd apps/web-app
pnpm lint
pnpm type-check

Security Scanning

Bandit (Python Security)

# From repo root
make bandit

# Or directly
cd services/api-gateway
source venv/bin/activate
bandit -c ../../.bandit -r app/

Safety (Python Dependencies)

cd services/api-gateway
source venv/bin/activate
pip install safety
safety check

npm audit (Frontend Dependencies)

pnpm audit

CI/CD

GitHub Actions Workflows

The project uses GitHub Actions for CI/CD:

  • Backend CI (.github/workflows/ci.yml)

    • Runs on changes to services/, tests/, backend configs
    • Linting, type checking, unit tests, E2E tests
    • Security scanning with Bandit

  • Frontend CI (.github/workflows/frontend-ci.yml)

    • Runs on changes to apps/, packages/, frontend configs
    • Linting, type checking, tests
    • Build verification

  • Security Scan (.github/workflows/security-scan.yml)

    • Scheduled security scans
    • Dependency vulnerability checks

Required Checks Before PR

Before opening a pull request, ensure:

# 1. Environment is valid
make check-env

# 2. All tests pass
make test
pnpm test

# 3. Linting passes
make lint
pnpm lint

# 4. Type checking passes
make type-check
pnpm type-check

# 5. Pre-commit hooks pass
pre-commit run --all-files

# 6. Security scans pass
make bandit

Troubleshooting

Backend Issues

Problem: ModuleNotFoundError: No module named 'app'

Solution: Ensure you're in the correct directory and virtual environment:

cd services/api-gateway
source venv/bin/activate
export PYTHONPATH=/path/to/VoiceAssist/services/api-gateway:$PYTHONPATH

Problem: Database connection errors

Solution: Ensure infrastructure services are running:

docker compose ps
docker compose up -d postgres redis qdrant

Frontend Issues

Problem: pnpm: command not found

Solution: Install pnpm globally:

npm install -g pnpm

Problem: Build errors with shared packages

Solution: Build packages in dependency order:

pnpm build

Problem: Port already in use

Solution: Change port in vite.config.ts or kill the process:

lsof -ti:5173 | xargs kill -9

Pre-commit Issues

Problem: Pre-commit hooks failing

Solution: Update hooks and run manually:

pre-commit autoupdate
pre-commit run --all-files

Additional Resources

Getting Help

← All documentationHome
Beginning of guide
End of guide