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:T1758, # Debugging Overview **Last Updated:** 2025-11-27 **Audience:** Developers, SREs, AI Assistants This guide provides a high-level overview of debugging VoiceAssist components. For detailed component-specific debugging, see the linked documents. --- ## Quick Reference: Where to Look | Symptom | First Place to Check | Document | | -------------------------- | ---------------------------------- | ----------------------------------------------- | | Backend 500 errors | API Gateway logs | [Backend Debugging](./DEBUGGING_BACKEND.md) | | Frontend not loading | Browser console, network tab | [Frontend Debugging](./DEBUGGING_FRONTEND.md) | | WebSocket disconnects | Realtime service logs | [Voice/Realtime](./DEBUGGING_VOICE_REALTIME.md) | | Voice transcription fails | STT service logs | [Voice/Realtime](./DEBUGGING_VOICE_REALTIME.md) | | Docs site 404s | Apache rewrite rules, static files | [Docs Site](./DEBUGGING_DOCS_SITE.md) | | Auth failures | JWT tokens, Redis session | [Backend Debugging](./DEBUGGING_BACKEND.md) | | Database connection errors | PostgreSQL logs, connection pool | [Backend Debugging](./DEBUGGING_BACKEND.md) | --- ## Logs and Metrics ### Backend Logs **Location:** `docker logs voiceassist-server -f` (VoiceAssist runs in Docker) **Key Log Files:** - API Gateway: `/var/log/api-gateway/` or stdout in container - Structured JSON logs with trace IDs **Log Levels:** - `DEBUG` - Verbose debugging - `INFO` - Normal operation - `WARNING` - Recoverable issues - `ERROR` - Failures requiring attention - `CRITICAL` - System-level failures ### Frontend Logs **Location:** Browser Developer Tools → Console **Key Areas:** - Network tab for API failures - Console for JavaScript errors - React DevTools for component state ### Infrastructure Metrics **Prometheus Metrics:** `http://localhost:8000/metrics` **Key Metrics:** - `http_requests_total` - Request counts by endpoint and status - `http_request_duration_seconds` - Latency histogram - `db_connection_pool_*` - Database connection health - `redis_*` - Cache performance - `rag_*` - RAG pipeline metrics --- ## Common Symptoms and Causes ### Backend Issues | Symptom | Likely Causes | | ------------------------- | ----------------------------------------------------- | | 500 Internal Server Error | Unhandled exception, database timeout, missing config | | 401 Unauthorized | Expired JWT, missing token, wrong audience | | 403 Forbidden | Insufficient role, RBAC policy violation | | 429 Too Many Requests | Rate limiting triggered | | 503 Service Unavailable | Dependency down (DB, Redis, Qdrant) | ### Frontend Issues | Symptom | Likely Causes | | ------------------ | --------------------------------------------------- | | Blank page | JavaScript error, missing env vars, CORS | | API calls failing | Network issues, wrong base URL, auth token expired | | State not updating | React state mutation, missing useEffect deps | | Slow rendering | Unoptimized re-renders, large lists without virtual | ### Voice/Realtime Issues | Symptom | Likely Causes | | ----------------------- | ------------------------------------------ | | WebSocket won't connect | CORS, proxy config, SSL termination | | Audio not recording | Browser permissions, MediaRecorder support | | Transcription empty | STT service down, audio format unsupported | | TTS not playing | Audio context suspended, codec issues | --- ## Investigation Workflow ### 1. Reproduce the Issue ```bash # Check container status docker ps --filter name=voiceassist # Watch logs in real-time docker logs voiceassist-server -f # Test API directly curl -X GET http://localhost:8000/health curl -X GET http://localhost:8000/ready ``` ### 2. Identify the Component ``` User Request ↓ [Frontend] → Check browser console ↓ [API Gateway] → Check service logs ↓ [Database/Redis/Qdrant] → Check dependency health ``` ### 3. Check Dependencies ```bash # Database psql -h localhost -U postgres -d voiceassist -c "SELECT 1" # Redis redis-cli ping # Qdrant curl http://localhost:6333/collections ``` ### 4. Review Recent Changes ```bash # Recent commits git log --oneline -10 # Recent logs from past hour docker logs voiceassist-server --since "1h" ``` --- ## Relevant Dashboards | Dashboard | URL | Purpose | | ----------------------- | --------------------------------------- | --------------------- | | API Health | `/health`, `/ready` | Service health checks | | Prometheus Metrics | `/metrics` | Raw metrics | | Grafana (if configured) | `http://localhost:3000` | Visualization | | Apache Status | `https://assist.asimo.io/server-status` | Web server metrics | --- ## Detailed Debugging Guides - [Backend Debugging](./DEBUGGING_BACKEND.md) - API Gateway, database, cache - [Frontend Debugging](./DEBUGGING_FRONTEND.md) - Web app, React components - [Voice & Realtime Debugging](./DEBUGGING_VOICE_REALTIME.md) - WebSocket, STT, TTS - [Docs Site Debugging](./DEBUGGING_DOCS_SITE.md) - Next.js, static export, Apache --- ## Related Documentation - [Operations Runbooks](../operations/runbooks/) - Step-by-step incident procedures - [Implementation Status](../overview/IMPLEMENTATION_STATUS.md) - Component status - [Backend Architecture](../BACKEND_ARCHITECTURE.md) - System design 6:["slug","debugging/DEBUGGING_OVERVIEW","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","debugging/DEBUGGING_OVERVIEW","c"],{"children":["__PAGE__?{\"slug\":[\"debugging\",\"DEBUGGING_OVERVIEW\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","debugging/DEBUGGING_OVERVIEW","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":"Debugging Overview"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","debugging/DEBUGGING_OVERVIEW.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/debugging/DEBUGGING_OVERVIEW.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":"Debugging Overview | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"High-level guide on how to debug VoiceAssist - logs, metrics, common symptoms, and where to look."}],["$","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