2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"] 4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""] 5:I[4126,[],""] 7:I[9630,[],""] 8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"] 9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"] a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"] b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"] 3:T314d, # VoiceAssist Development Setup Guide This guide walks you through setting up your local development environment for VoiceAssist. ## Table of Contents - [Prerequisites](#prerequisites) - [Backend Setup](#backend-setup) - [Frontend Setup](#frontend-setup) - [Development Tooling](#development-tooling) - [Running the Application](#running-the-application) - [Testing](#testing) - [CI/CD](#cicd) --- ## 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) ### Recommended Tools - **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 ```bash git clone git@github.com:mohammednazmy/VoiceAssist.git cd VoiceAssist ``` ### 2. Set Up Python Virtual Environment ```bash cd services/api-gateway python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` ### 3. Install Backend Dependencies ```bash pip install -r requirements.txt ``` ### 4. Configure Environment Variables ```bash # From repo root cp .env.example .env ``` Edit `.env` and configure the following required variables: ```bash # Core ENVIRONMENT=development DEBUG=true # Database POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=voiceassist POSTGRES_PASSWORD= POSTGRES_DB=voiceassist_db DATABASE_URL=postgresql://:@localhost:5432/voiceassist_db # Redis REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= # Qdrant (vector database) QDRANT_HOST=localhost QDRANT_PORT=6333 # Security SECRET_KEY= JWT_SECRET= JWT_ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 REFRESH_TOKEN_EXPIRE_DAYS=7 # OpenAI 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= ``` ### 5. Validate Environment ```bash # From repo root make check-env ``` This command validates that all required environment variables are set. ### 6. Start Infrastructure Services ```bash # From repo root docker compose up -d postgres redis qdrant ``` ### 7. Run Database Migrations ```bash cd services/api-gateway source venv/bin/activate alembic upgrade head ``` --- ## Frontend Setup ### 1. Install pnpm If you don't have pnpm installed: ```bash npm install -g pnpm ``` Or see [pnpm installation docs](https://pnpm.io/installation) for alternative methods. ### 2. Install Frontend Dependencies ```bash # From repo root pnpm install ``` This installs dependencies for all packages in the monorepo (apps and shared packages). ### 3. Build Shared Packages ```bash pnpm build ``` This builds all shared packages that other apps depend on. ### 4. Start Development Server ```bash # 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: ```bash # 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 ```bash cd services/api-gateway source venv/bin/activate pip install pre-commit ``` #### Setup hooks ```bash # From repo root pre-commit install ``` This installs git hooks that run automatically before each commit. #### Manual Run ```bash # 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 ### Full Stack (Recommended) ```bash # Start all services (backend + frontend + infrastructure) docker compose up -d # View logs docker compose logs -f api-gateway ``` Access the application: - **Web App**: http://localhost:5173 - **Admin Panel**: http://localhost:5174 - **API Gateway**: http://localhost:8000 - **API Docs**: http://localhost:8000/docs ### Backend Only ```bash cd services/api-gateway source venv/bin/activate uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` ### Frontend Only ```bash # 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 ```bash # 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 ```bash # 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: ```bash 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: ```json { "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: ```bash 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 ```bash # 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 ```bash # From repo root pnpm test # Or in specific package cd apps/web-app pnpm test ``` ### Test Coverage ```bash # 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 ```bash # 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 ```bash # 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) ```bash # From repo root make bandit # Or directly cd services/api-gateway source venv/bin/activate bandit -c ../../.bandit -r app/ ``` ### Safety (Python Dependencies) ```bash cd services/api-gateway source venv/bin/activate pip install safety safety check ``` ### npm audit (Frontend Dependencies) ```bash 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: ```bash # 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: ```bash 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: ```bash docker compose ps docker compose up -d postgres redis qdrant ``` ### Frontend Issues **Problem**: `pnpm: command not found` **Solution**: Install pnpm globally: ```bash npm install -g pnpm ``` **Problem**: Build errors with shared packages **Solution**: Build packages in dependency order: ```bash pnpm build ``` **Problem**: Port already in use **Solution**: Change port in vite.config.ts or kill the process: ```bash lsof -ti:5173 | xargs kill -9 ``` ### Pre-commit Issues **Problem**: Pre-commit hooks failing **Solution**: Update hooks and run manually: ```bash pre-commit autoupdate pre-commit run --all-files ``` --- ## Additional Resources - [Contributing Guide](../CONTRIBUTING.md) - [Architecture Documentation](./ARCHITECTURE_V2.md) - [API Documentation](http://localhost:8000/docs) (when running) - [Frontend Roadmap](./client-implementation/) - [HIPAA Compliance Matrix](./HIPAA_COMPLIANCE_MATRIX.md) - [Deployment Guide](./DEPLOYMENT_GUIDE.md) --- ## Getting Help - **Issues**: https://github.com/mohammednazmy/VoiceAssist/issues - **Discussions**: https://github.com/mohammednazmy/VoiceAssist/discussions - **Internal Docs**: See `docs/` directory for detailed technical documentation 6:["slug","DEVELOPMENT_SETUP","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","DEVELOPMENT_SETUP","c"],{"children":["__PAGE__?{\"slug\":[\"DEVELOPMENT_SETUP\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","DEVELOPMENT_SETUP","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"Development Setup"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","DEVELOPMENT_SETUP.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/DEVELOPMENT_SETUP.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]] c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"Development Setup | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"This guide walks you through setting up your local development environment for VoiceAssist."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]] 1:null