dictation-service/PROJECT_STRUCTURE.md

AI Dictation Service - Clean Project Structure

📁 Directory Organization

dictation-service/
├── 📁 src/
│   └── 📁 dictation_service/
│       ├── 🔧 ai_dictation_simple.py      # Main AI dictation service (ACTIVE)
│       ├── 🔧 ai_dictation.py             # Full version with GTK GUI
│       ├── 🔧 enhanced_dictation.py       # Original enhanced dictation
│       ├── 🔧 vosk_dictation.py           # Basic dictation
│       └── 🔧 main.py                     # Entry point
│
├── 📁 scripts/
│   ├── 🔧 fix_service.sh                  # Service setup with sudo
│   ├── 🔧 setup-dual-keybindings.sh       # Alt+D & Super+Alt+D setup
│   ├── 🔧 setup_super_d_manual.sh         # Manual Super+Alt+D setup
│   ├── 🔧 setup-keybindings.sh            # Original Alt+D setup
│   ├── 🔧 setup-keybindings-manual.sh     # Manual setup
│   ├── 🔧 switch-model.sh                 # Model switching tool
│   ├── 🔧 toggle-conversation.sh          # Conversation mode toggle
│   └── 🔧 toggle-dictation.sh             # Dictation mode toggle
│
├── 📁 tests/
│   ├── 🔧 run_all_tests.sh                # Comprehensive test runner
│   ├── 🔧 test_original_dictation.py      # Original dictation tests
│   ├── 🔧 test_suite.py                   # AI conversation tests
│   ├── 🔧 test_vllm_integration.py        # VLLM integration tests
│   ├── 🔧 test_imports.py                 # Import tests
│   └── 🔧 test_run.py                     # Runtime tests
│
├── 📁 docs/
│   ├── 📖 AI_DICTATION_GUIDE.md            # Complete user guide
│   ├── 📖 INSTALL.md                      # Installation instructions
│   ├── 📖 TESTING_SUMMARY.md              # Test coverage overview
│   ├── 📖 TEST_RESULTS_AND_FIXES.md       # Test results and fixes
│   ├── 📖 README.md                       # Project overview
│   └── 📖 CLAUDE.md                       # Claude configuration
│
├── 📁 ~/.shared/models/vosk-models/       # Shared model directory
│   ├── 🧠 vosk-model-en-us-0.22/          # Best accuracy model
│   ├── 🧠 vosk-model-en-us-0.22-lgraph/   # Good balance model
│   └── 🧠 vosk-model-small-en-us-0.15/    # Fast model
│
├── ⚙️ pyproject.toml                      # Python dependencies
├── ⚙️ uv.lock                             # Dependency lock file
├── ⚙️ .python-version                     # Python version
├── ⚙️ dictation.service                   # systemd service config
├── ⚙️ .gitignore                          # Git ignore rules
└── ⚙️ .venv/                              # Python virtual environment

🎯 Key Features by Directory

src/ - Core Application Logic

• Main Service: ai_dictation_simple.py (currently active)
• VLLM Integration: OpenAI-compatible API client
• TTS Engine: Text-to-speech synthesis
• Conversation Manager: Persistent context management
• Audio Processing: Real-time speech recognition

scripts/ - System Integration

• Keybinding Setup: Super+Alt+D for AI conversation, Alt+D for dictation
• Service Management: systemd service configuration
• Model Switching: Easy switching between VOSK models
• Mode Toggling: Scripts to start/stop dictation and conversation modes

tests/ - Comprehensive Testing

• 100+ Test Cases: Covering all functionality
• Integration Tests: VLLM, audio, and system integration
• Performance Tests: Response time and resource usage
• Error Handling: Failure and recovery scenarios

docs/ - Documentation

• User Guide: Complete setup and usage instructions
• Test Results: Comprehensive testing coverage report
• Installation: Step-by-step setup instructions

🚀 Quick Start Commands

# Setup keybindings (Super+Alt+D for AI, Alt+D for dictation)
./scripts/setup-dual-keybindings.sh

# Start service with sudo fix
./scripts/fix_service.sh

# Test VLLM integration
python tests/test_vllm_integration.py

# Run all tests
cd tests && ./run_all_tests.sh

# Switch speech recognition models
./scripts/switch-model.sh

🔧 Configuration

Keybindings:

• Super+Alt+D: AI conversation mode (with persistent context)
• Alt+D: Traditional dictation mode

Models:

• Speech: VOSK models from ~/.shared/models/vosk-models/
• AI: Qwen/Qwen2.5-7B-Instruct-GPTQ-Int4 (VLLM)

API Endpoints:

• VLLM: http://127.0.0.1:8000/v1
• API Key: vllm-api-key

📊 Clean Project Benefits

✅ Organization:

• Logical Structure: Separate concerns into distinct directories
• Easy Navigation: Clear purpose for each directory
• Scalable: Easy to add new features and tests

✅ Maintainability:

• Modular Code: Independent components and services
• Version Control: Clean git history without clutter
• Testing Isolation: Tests separate from production code

✅ Deployment:

• Service Ready: systemd configuration included
• Shared Resources: Models in shared directory for multi-project use
• Dependency Management: uv package manager with lock file

---

🎉 Your AI Dictation Service is now perfectly organized and ready for production use!

The clean structure makes it easy to maintain, extend, and deploy your conversational AI phone call system with persistent conversation context.