Docs / Raw

Development Phases

Sourced from docs/DEVELOPMENT_PHASES.md

Edit on GitHub

⚠️ LEGACY V1 DOCUMENT – NOT CANONICAL FOR V2 This describes the original 20-phase plan. For the current architecture and phases, see:

VoiceAssist Development Phases

Overview

This document breaks down VoiceAssist development into self-contained phases, each designed to be completed by Claude Code in a single continuous session (3-6 hours of focused work).

Development Approach

  • Local-First: All development happens on MacBook Pro
  • Incremental: Each phase builds on previous phases
  • Self-Contained: Clear entry/exit criteria for each phase
  • Testable: Every phase includes verification steps
  • Documented: Update docs as you build

Phase Prerequisites

Before starting any phase, Claude Code should:

  1. Read all documentation in ~/VoiceAssist/docs/
  2. Check current status of the project
  3. Verify prerequisites for the phase are met
  4. Review what was completed in previous phases

Phase Structure

Each phase document includes:

  • Goal: What this phase accomplishes
  • Prerequisites: What must exist before starting
  • Entry Checklist: Verify before beginning
  • Tasks: Step-by-step implementation guide
  • Testing: How to verify success
  • Documentation Updates: What docs to update
  • Exit Checklist: What should exist when done
  • Next Phase: What comes next

Phase Overview

Foundation Phases (1-3)

Phase 1: Local Development Environment (~4 hours)

  • Install all dependencies on MacBook Pro
  • Set up local databases (PostgreSQL, Redis, Qdrant)
  • Create project structure
  • Basic FastAPI app with health check

Phase 2: Database Schema & Models (~3 hours)

  • Define SQLAlchemy models
  • Create migrations with Alembic
  • Set up pgvector extension
  • Create Qdrant collections

Phase 3: Authentication System (~4 hours)

  • JWT authentication
  • User registration/login
  • API key management
  • Protected endpoints

AI Integration Phases (4-5)

Phase 4: Local LLM Integration (~3 hours)

  • Ollama setup and configuration
  • LLM service wrapper
  • Basic chat endpoint
  • Test local inference

Phase 5: OpenAI Realtime API (~5 hours)

  • WebSocket endpoint for voice
  • OpenAI Realtime API proxy
  • Audio streaming setup
  • Voice conversation testing

File System & Privacy Phases (6-7)

Phase 6: File System Access & Privacy (~5 hours)

  • File indexing service
  • Privacy classifier implementation
  • Local vector search
  • File query endpoints

Phase 7: macOS System Integrations (~6 hours)

  • Calendar access (EventKit/AppleScript)
  • Email integration
  • Reminders and Notes
  • Test all integrations

Medical Knowledge Base Phases (8-11)

Phase 8: PDF Processing Pipeline (~5 hours)

  • PDF upload endpoint
  • Text extraction (PyPDF2, pdfplumber)
  • OCR integration (Tesseract)
  • Chunking strategy implementation

Phase 9: Embedding & Vector Storage (~4 hours)

  • Embedding generation (OpenAI)
  • Store in Qdrant with metadata
  • Batch processing
  • Test retrieval

Phase 10: RAG System Implementation (~5 hours)

  • Semantic search
  • Context assembly
  • Citation generation
  • Medical query endpoint with sources

Phase 11: PubMed Integration (~4 hours)

  • PubMed API client
  • Search and download
  • Journal article processing
  • Integration with RAG system

Frontend Phases (12-14)

Phase 12: Web App - Core Chat Interface (~5 hours)

  • React + TypeScript + Vite setup
  • Chat UI components
  • Message streaming
  • WebSocket connection
  • File upload

Phase 13: Web App - Voice Interface (~4 hours)

  • Microphone input setup
  • Web Audio API integration
  • Voice controls and visualization
  • Audio playback

Phase 14: Web App - History & Settings (~3 hours)

  • Conversation history
  • Search functionality
  • User settings page
  • Export conversations

Admin Panel Phases (15-16)

Phase 15: Admin Panel - Dashboard (~4 hours)

  • React setup with Tremor
  • System overview dashboard
  • Real-time metrics
  • Service status indicators

Phase 16: Admin Panel - Knowledge Base UI (~4 hours)

  • Document upload interface
  • Document management table
  • Indexing controls
  • Analytics views

External Integrations Phase (17)

Phase 17: External Service Integrations (~5 hours)

  • Nextcloud WebDAV integration
  • OpenEvidence API (if available)
  • Clinical guidelines scrapers
  • Web search integration

Testing & Polish Phases (18-19)

Phase 18: Integration Testing & Bug Fixes (~6 hours)

  • Write integration tests
  • End-to-end testing
  • Bug fixes and refinements
  • Performance optimization

Phase 19: Documentation Site (~4 hours)

  • Next.js + MDX setup
  • Content creation
  • Search functionality
  • Deploy locally

Deployment Phase (20)

Phase 20: Ubuntu Deployment (~5 hours)

  • Create deployment script
  • Ubuntu-specific configuration
  • Production environment setup
  • Deployment testing

Total Estimated Time

  • 20 Phases × ~4.5 hours average = ~90 hours
  • Working 4 hours/day = ~23 days
  • Working on weekends = ~1 month of development

Phase Status Tracking

Create a PHASE_STATUS.md file to track progress:

# Phase Completion Status

- [x] Phase 1: Local Development Environment - Completed 2024-11-20
- [x] Phase 2: Database Schema & Models - Completed 2024-11-21
- [ ] Phase 3: Authentication System - In Progress
- [ ] Phase 4: Local LLM Integration - Not Started
      ...

Starting a Phase

When starting a new phase:

cd ~/VoiceAssist
# Read the phase document
cat docs/phases/PHASE_XX_NAME.md
# Check prerequisites
# Begin implementation
# Test thoroughly
# Update documentation
# Mark phase as complete in PHASE_STATUS.md

Phase Dependencies

Phase 1 (Environment)
    ↓
Phase 2 (Database)
    ↓
Phase 3 (Auth)
    ↓
Phase 4 (Local LLM) ──┐
Phase 5 (OpenAI)      ├─→ Phase 12 (Web Chat)
Phase 6 (Files)       │       ↓
Phase 7 (Integrations)┘   Phase 13 (Voice)
    ↓                       ↓
Phase 8 (PDF)          Phase 14 (History)
    ↓                       ↓
Phase 9 (Embeddings)   Phase 15 (Admin)
    ↓                       ↓
Phase 10 (RAG)         Phase 16 (Admin KB)
    ↓
Phase 11 (PubMed)
    ↓
Phase 17 (External)
    ↓
Phase 18 (Testing)
    ↓
Phase 19 (Docs Site)
    ↓
Phase 20 (Deploy)

Critical Success Factors

  1. Complete one phase before starting the next
  2. Test thoroughly at each phase
  3. Update documentation as you go
  4. Commit code after each phase
  5. Verify all exit criteria before moving on

Working with Claude Code

Each phase document is designed to be given to Claude Code as a prompt:

"Please read ~/VoiceAssist/docs/phases/PHASE_03_AUTHENTICATION.md
and implement this phase. Check the prerequisites, verify the entry
checklist, complete all tasks, run tests, update documentation,
and verify exit criteria."

Claude Code will:

  • Read the phase instructions
  • Check what already exists
  • Implement the required features
  • Write tests
  • Update relevant documentation
  • Verify completion criteria

Phase Document Location

All phase documents are in: ~/VoiceAssist/docs/phases/

  • PHASE_01_LOCAL_ENVIRONMENT.md
  • PHASE_02_DATABASE_SCHEMA.md
  • PHASE_03_AUTHENTICATION.md
  • ... (all 20 phases)

Next Steps

  1. Review this document
  2. Read LOCAL_DEVELOPMENT.md for local setup details
  3. Start with Phase 1
  4. Work through phases sequentially
  5. Track progress in PHASE_STATUS.md
← All documentationHome
Beginning of guide
End of guide