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:T27da,
# Docs Site Debugging Guide
**Last Updated:** 2025-12-03
**Component:** `apps/docs-site/`
**Live Site:** https://assistdocs.asimo.io
---
## Architecture Overview
The docs site is a **static Next.js export** served by Apache:
```
docs/*.md → Next.js build → static HTML → Apache → assistdocs.asimo.io
(apps/docs-site) (out/) (rewrite rules)
```
Key points:
- All pages are pre-rendered at build time
- No server-side rendering or API routes
- Apache rewrite rules handle clean URLs (no .html extension)
- JSON endpoints are static files generated at build
---
## Symptoms
### 404 Not Found
**Likely Causes:**
- File not generated during build
- Apache rewrite rules not working
- Route not in `generateStaticParams()`
- File permissions issue
**Steps to Investigate:**
1. Check if file exists in output:
```bash
# For route /ai/onboarding, check:
ls -la /var/www/assistdocs.asimo.io/ai/onboarding.html
```
2. Check Apache rewrite logs:
```bash
sudo tail -f /var/log/apache2/assistdocs-error.log
```
3. Test with explicit .html:
```bash
curl -I https://assistdocs.asimo.io/ai/onboarding.html
# vs
curl -I https://assistdocs.asimo.io/ai/onboarding
```
4. Verify Apache rewrite rules:
```bash
sudo cat /etc/apache2/sites-available/assistdocs.asimo.io-le-ssl.conf | grep -A5 "RewriteRule"
```
**Common Fixes:**
```bash
# Ensure rewrite module enabled
sudo a2enmod rewrite
# Required rewrite rules in Apache config:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI}.html -f
RewriteRule ^(.*)$ $1.html [L]
```
**Relevant Code Paths:**
- `apps/docs-site/src/app/docs/[...slug]/page.tsx` - Dynamic route
- `apps/docs-site/src/lib/docs.ts` - `listAllDocPaths()` function
- Apache config: `/etc/apache2/sites-available/assistdocs.asimo.io-le-ssl.conf`
---
### Build Failures
**Likely Causes:**
- Invalid markdown frontmatter
- Missing dependency
- TypeScript errors
- Route not generating static params
**Steps to Investigate:**
1. Run build locally:
```bash
cd apps/docs-site
pnpm build
```
2. Check for TypeScript errors:
```bash
pnpm tsc --noEmit
```
3. Validate frontmatter:
```bash
pnpm validate:metadata
```
4. Check for missing `generateStaticParams`:
```
Error: Page "/docs/[...slug]" is missing "generateStaticParams()"
```
**Common Fixes:**
```typescript
// Every dynamic route needs generateStaticParams for static export
export function generateStaticParams() {
const paths = listAllDocPaths();
return paths.map((path) => ({
slug: path.split("/"),
}));
}
```
**Relevant Code Paths:**
- `apps/docs-site/next.config.ts` - `output: "export"`
- `apps/docs-site/src/lib/docs.ts` - Path generation
---
### Agent JSON Endpoints Not Working
**Symptoms:**
- `/agent/index.json` returns 404
- `/agent/docs.json` empty or outdated
**Steps to Investigate:**
1. Check files exist:
```bash
ls -la /var/www/assistdocs.asimo.io/agent/
# Should have index.json and docs.json
```
2. Regenerate agent JSON:
```bash
cd apps/docs-site
pnpm generate-agent-json
```
3. Verify public directory:
```bash
ls -la apps/docs-site/public/agent/
```
4. Re-run build:
```bash
pnpm --filter docs-site build
```
**Relevant Code Paths:**
- `apps/docs-site/scripts/generate-agent-json.js`
- `apps/docs-site/public/agent/` - Static JSON files
- `apps/docs-site/package.json` - prebuild script
---
### Search Not Working
**Symptoms:**
- Search modal shows no results
- `/search-index.json` not loading
**Steps to Investigate:**
1. Check search index exists:
```bash
ls -la /var/www/assistdocs.asimo.io/search-index.json
# Should be several MB
```
2. Verify JSON is valid:
```bash
jq . /var/www/assistdocs.asimo.io/search-index.json | head -20
```
3. Check generation:
```bash
cd apps/docs-site
pnpm generate-search-index
```
4. Test search index fetch:
```bash
curl -I https://assistdocs.asimo.io/search-index.json
```
**Relevant Code Paths:**
- `apps/docs-site/scripts/generate-search-index.js`
- `apps/docs-site/src/components/SearchModal.tsx`
---
### Markdown Not Rendering
**Symptoms:**
- Raw markdown shown instead of HTML
- Code blocks not highlighted
- Tables broken
**Steps to Investigate:**
1. Check MarkdownRenderer component:
```bash
# Look for errors in console about react-markdown
```
2. Verify dependencies:
```bash
cd apps/docs-site
pnpm list | grep -E "react-markdown|remark|syntax-highlight"
```
3. Check markdown content:
```bash
# Look for invalid syntax in the .md file
```
**Common Fixes:**
```typescript
// In MarkdownRenderer.tsx
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
{content}
```
**Relevant Code Paths:**
- `apps/docs-site/src/components/MarkdownRenderer.tsx`
- `apps/docs-site/package.json` - react-markdown dependency
---
### Metadata Not Showing
**Symptoms:**
- Doc page missing status badge
- Owner/audience not displayed
- Frontmatter not parsed
**Steps to Investigate:**
1. Check frontmatter format:
```yaml
---
title: My Document
slug: my-document
status: stable
lastUpdated: "2025-11-27" # Must be quoted string!
audience: ["human", "agent"]
---
```
2. Validate with script:
```bash
cd apps/docs-site
pnpm validate:metadata
```
3. Check parsing logic:
```bash
# Look for Date object handling
# gray-matter auto-parses dates which can cause issues
```
**Relevant Code Paths:**
- `apps/docs-site/src/lib/docs.ts` - `parseMetadata()`
- `apps/docs-site/src/components/DocPage.tsx` - Metadata display
---
### AI-Docs / Semantic Search Not Working
**Symptoms:**
- `docs_search` tool returns empty results
- AI agents can't find documentation via semantic search
- Qdrant collection missing or outdated
**Steps to Investigate:**
1. Check Qdrant is running:
```bash
curl http://localhost:6333/collections
# Should list 'platform_docs' collection
```
2. Verify collection exists and has documents:
```bash
curl http://localhost:6333/collections/platform_docs
# Check 'vectors_count' is > 0
```
3. Check embedding script output:
```bash
cd /home/asimo/VoiceAssist
python scripts/embed-docs.py --dry-run
# Shows which docs would be embedded
```
4. Re-index documentation:
```bash
# Force re-embed all docs
python scripts/embed-docs.py --force
```
5. Verify docs search tool is registered:
```bash
# Check tool registration (note: server/ is deprecated, but tool stub still exists there)
grep -r "docs_search" server/app/tools/
# Production implementation is via services/api-gateway
```
**Common Fixes:**
```bash
# 1. Ensure Qdrant is running
docker compose up -d qdrant
# 2. Re-embed documentation
python scripts/embed-docs.py --force
# 3. Restart API server to pick up changes
docker compose restart api-gateway
# 4. Verify tool is working
curl -X POST http://localhost:8000/api/tools/docs_search \
-H "Content-Type: application/json" \
-d '{"query": "voice pipeline"}'
```
**Relevant Code Paths:**
- `scripts/embed-docs.py` - Embedding script
- `services/api-gateway/app/tools/` - Production tool implementations
- `server/app/tools/docs_search_tool.py` - Legacy search tool (deprecated)
- `docker-compose.yml` - Qdrant service configuration
**Related Docs:**
- [Internal Docs System](../INTERNAL_DOCS_SYSTEM.md#ai-integration-ai-docs)
- [Agent API Reference](../ai/AGENT_API_REFERENCE.md#ai-docs-semantic-search)
---
## Build and Deploy Process
### Local Development
```bash
cd apps/docs-site
pnpm dev
# Open http://localhost:3000
```
### Build Static Export
```bash
cd apps/docs-site
pnpm build
# Output in out/ directory
```
### Deploy to Production
```bash
# 1. Build
pnpm --filter docs-site build
# 2. Copy to web root
sudo cp -r apps/docs-site/out/* /var/www/assistdocs.asimo.io/
# 3. Verify permissions
sudo chown -R www-data:www-data /var/www/assistdocs.asimo.io/
# 4. Test (docs site has no /health endpoint - use these instead)
curl -I https://assistdocs.asimo.io/ # Homepage
curl https://assistdocs.asimo.io/agent/index.json # AI agent discovery
curl https://assistdocs.asimo.io/search-index.json # Search index
```
### Apache Configuration
Required config at `/etc/apache2/sites-available/assistdocs.asimo.io-le-ssl.conf`:
```apache
ServerName assistdocs.asimo.io
DocumentRoot /var/www/assistdocs.asimo.io
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
DirectoryIndex index.html
# Clean URLs - serve .html files without extension
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI}.html -f
RewriteRule ^(.*)$ $1.html [L]
# SSL certificates
SSLCertificateFile /etc/letsencrypt/live/assistdocs.asimo.io/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/assistdocs.asimo.io/privkey.pem
```
---
## Validation Scripts
```bash
# Validate all frontmatter
pnpm validate:metadata
# Check internal links
pnpm check:links
# Generate agent JSON
pnpm generate:agent-json
# Full validation
pnpm validate:all
```
---
## Common Error Messages
| Error | Cause | Fix |
| ---------------------------------------- | ---------------------------- | ---------------------------------- |
| `Page is missing generateStaticParams()` | Dynamic route without params | Add function returning all paths |
| `Objects are not valid as React child` | Date object in frontmatter | Convert to string in parseMetadata |
| `MDX compilation error` | Invalid JSX in markdown | Use react-markdown instead |
| `ENOENT: no such file or directory` | Doc file moved/deleted | Update references |
---
## Related Documentation
- [Debugging Overview](./DEBUGGING_OVERVIEW.md)
- [Internal Docs System](../INTERNAL_DOCS_SYSTEM.md)
- [Agent API Reference](../ai/AGENT_API_REFERENCE.md)
6:["slug","debugging/DEBUGGING_DOCS_SITE","c"]
0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","debugging/DEBUGGING_DOCS_SITE","c"],{"children":["__PAGE__?{\"slug\":[\"debugging\",\"DEBUGGING_DOCS_SITE\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","debugging/DEBUGGING_DOCS_SITE","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":"Docs Site Debugging Guide"}],["$","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_DOCS_SITE.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/debugging/DEBUGGING_DOCS_SITE.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":"Docs Site Debugging Guide | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Debug Next.js docs site, static export, Apache routing, and documentation issues."}],["$","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