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:T2a7d, # Internal Documentation System This document describes the documentation infrastructure for VoiceAssist, including validation scripts, quality gates, and how to maintain documentation quality. ## Overview The VoiceAssist documentation system consists of: | Component | Purpose | Location | | ------------------ | ------------------------------- | -------------------------------------------------- | | Docs Directory | Markdown source files | `docs/` | | Docs Site | Next.js documentation website | `apps/docs-site/` | | Agent API | Machine-readable JSON endpoints | See [Agent Endpoints](#agent-json-endpoints) below | | Validation Scripts | Quality gates and linting | `apps/docs-site/scripts/` | | API Doc Generator | OpenAPI introspection | `services/api-gateway/tools/` | ### Agent JSON Endpoints Static JSON endpoints served at `assistdocs.asimo.io`: | Endpoint | Purpose | | --------------------------- | -------------------------------------------------- | | `/agent/index.json` | Documentation system metadata and discovery | | `/agent/docs.json` | Full document list with metadata (incl ai_summary) | | `/agent/docs-summary.json` | AI-friendly summaries organized by category | | `/agent/tasks.json` | Common agent tasks with commands | | `/agent/code-examples.json` | Code examples extracted from documentation | | `/agent/health.json` | Docs health metrics: coverage, freshness, status | | `/agent/schema.json` | JSON Schema for API response types | | `/search-index.json` | Full-text search index (Fuse.js) | For detailed usage, see [Agent API Reference](ai/AGENT_API_REFERENCE.md). ## Validation Scripts ### validate-metadata.mjs **Purpose:** Validates YAML frontmatter against the metadata schema. **Script:** `apps/docs-site/scripts/validate-metadata.mjs` **Command:** ```bash cd apps/docs-site pnpm validate:metadata ``` **What it checks:** - Required fields: `title`, `slug`, `status`, `lastUpdated` - Enum values: `status`, `stability`, `owner`, `audience` - Date format: ISO 8601 (YYYY-MM-DD) - Array types: `tags`, `audience`, `relatedServices` **When to run:** - Before committing documentation changes - In CI/CD pipelines - During pre-release validation **Example output:** ``` Validating documentation metadata... docs/VOICE_MODE_PIPELINE.md: WARNING: Missing recommended field: status ============================================================ Files scanned: 42 Files with issues: 3 Total errors: 0 Total warnings: 5 ============================================================ Validation passed with warnings. ``` --- ### check-links.mjs **Purpose:** Detects broken internal links in markdown files. **Script:** `apps/docs-site/scripts/check-links.mjs` **Command:** ```bash cd apps/docs-site pnpm check:links ``` **What it checks:** - Internal markdown links (e.g., `[text](./example.md)`) - Cross-file references - Relative path resolution **When to run:** - After renaming or moving documentation files - Before merging documentation PRs - During periodic documentation audits --- ### validate:all **Purpose:** Runs all validation scripts in sequence. **Command:** ```bash cd apps/docs-site pnpm validate:all ``` **Runs:** 1. `pnpm validate:metadata` - Frontmatter validation 2. `pnpm check:links` - Broken link detection 3. `pnpm check:freshness` - Stale doc detection (warns if >30 days) 4. `pnpm validate:api-sync` - API coverage check **When to run:** - Before releasing documentation updates - In CI/CD pipelines as a blocking gate - During documentation audits --- ### check-freshness.mjs **Purpose:** Detects stale documentation files based on lastUpdated date. **Script:** `apps/docs-site/scripts/check-freshness.mjs` **Command:** ```bash cd apps/docs-site pnpm check:freshness ``` **What it checks:** - Documents with lastUpdated older than 30 days (warning) - Documents with lastUpdated older than 90 days (error) - Missing lastUpdated fields --- ### validate-api-sync.mjs **Purpose:** Verifies API documentation coverage against OpenAPI spec. **Script:** `apps/docs-site/scripts/validate-api-sync.mjs` **Command:** ```bash cd apps/docs-site pnpm validate:api-sync # Warn on undocumented endpoints pnpm validate:api-sync --strict # Fail on undocumented endpoints ``` **What it checks:** - Endpoints in OpenAPI spec but missing from documentation - Endpoints documented but not in OpenAPI spec - Parameter mismatches --- ### sync-openapi.mjs **Purpose:** Fetches and caches OpenAPI spec from API gateway. **Script:** `apps/docs-site/scripts/sync-openapi.mjs` **Command:** ```bash cd apps/docs-site pnpm sync:openapi # Check for changes (dry run) pnpm sync:openapi --update # Update local cache ``` --- ### generate:api-docs **Purpose:** Regenerates API documentation from OpenAPI spec. **Command:** ```bash cd apps/docs-site pnpm generate:api-docs ``` **Script:** `services/api-gateway/tools/generate_api_docs.py` **What it does:** 1. Fetches OpenAPI spec from running API gateway (or uses cached spec) 2. Generates `docs/api-reference/API_ROUTES.md` (Markdown) 3. Generates `docs/api-reference/api-routes.json` (JSON) 4. Updates route counts and documentation **When to run:** - After adding/modifying API endpoints - Before major releases - To verify API-documentation alignment **Requirements:** - Python 3.8+ - Running API gateway (or existing `openapi.json`) --- ## Other Validation Tools ### validate-docs.mjs **Purpose:** Legacy documentation validator (deprecated in favor of validate-metadata.mjs). **Command:** ```bash pnpm validate-docs ``` ### generate-search-index.js **Purpose:** Generates search index for docs site search functionality. **Command:** ```bash pnpm generate-search-index ``` **Note:** Runs automatically before `dev` and `build`. ### generate-api-reference.mjs **Purpose:** Generates API reference page data. **Command:** ```bash pnpm generate:api-reference ``` --- ## AI Integration (AI-Docs) The documentation system integrates with the AI assistant for semantic search. ### embed-docs.py **Purpose:** Embeds documentation into Qdrant for semantic search. **Script:** `scripts/embed-docs.py` **Command:** ```bash python scripts/embed-docs.py # Incremental update python scripts/embed-docs.py --force # Force re-index all python scripts/embed-docs.py --dry-run # Preview without indexing python scripts/embed-docs.py --collection NAME # Custom collection ``` **Configuration:** | Property | Value | | ------------------- | ---------------------- | | **Collection** | `platform_docs` | | **Embedding Model** | text-embedding-3-small | | **Dimensions** | 1536 | | **Distance Metric** | Cosine | ### docs_search_tool.py **Purpose:** LLM tool for semantic documentation search. **Script:** `server/app/tools/docs_search_tool.py` _(legacy location - `server/` is deprecated; current implementation uses Qdrant-backed semantic search via the AI-Docs pipeline)_ **Functions:** ```python # docs_search - Semantic search across documentation docs_search(query: str, category: str = None, max_results: int = 5) # docs_get_section - Retrieve full section content docs_get_section(doc_path: str, section: str = None) ``` **Usage:** The AI assistant automatically uses these tools when answering questions about the platform. --- ## Metadata Schema All documentation files should include YAML frontmatter. See [DOCUMENTATION_METADATA_STANDARD.md](./DOCUMENTATION_METADATA_STANDARD.md) for the full schema. ### Quick Reference ```yaml --- title: Document Title # Required slug: path/to-document # Required (URL path) summary: One-line description # Recommended status: stable # Required: draft|experimental|stable|deprecated stability: production # Optional: production|beta|experimental|legacy owner: backend # Optional: backend|frontend|infra|sre|docs|product|security|mixed lastUpdated: "2025-12-02" # Required: ISO date audience: ["human", "agent"] # Optional: who should read this tags: ["api", "architecture"] # Optional: searchable tags relatedServices: ["api-gateway"] # Optional: related services --- ``` ### Status Values | Status | Meaning | | -------------- | ------------------------------------ | | `draft` | Work in progress, may be incomplete | | `experimental` | New approach, subject to change | | `stable` | Production-ready, reviewed | | `deprecated` | Superseded, maintained for reference | ### Audience Values | Audience | Description | | ---------- | ------------------------------ | | `human` | Human developers and operators | | `agent` | AI coding assistants | | `backend` | Backend developers | | `frontend` | Frontend developers | | `devops` | DevOps/SRE engineers | | `admin` | System administrators | | `user` | End users | --- ## CI/CD Integration ### GitHub Actions Example ```yaml name: Documentation Quality on: pull_request: paths: - "docs/**" - "apps/docs-site/**" jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 - uses: actions/setup-node@v4 with: node-version: "20" cache: "pnpm" - run: pnpm install - run: cd apps/docs-site && pnpm validate:all ``` ### Pre-commit Hook Add to `.husky/pre-commit`: ```bash #!/bin/sh cd apps/docs-site pnpm validate:metadata ``` --- ## Related Documentation - [Implementation Status](./overview/IMPLEMENTATION_STATUS.md) - Component status tracking - [Documentation Metadata Standard](./DOCUMENTATION_METADATA_STANDARD.md) - Full metadata schema - [Agent API Reference](./ai/AGENT_API_REFERENCE.md) - Machine-readable endpoints - [Agent Onboarding](./ai/AGENT_ONBOARDING.md) - AI assistant quick start --- ## Version History | Version | Date | Changes | | ------- | ---------- | ----------------------------------------------------------------------- | | 1.1.0 | 2025-12-02 | Added new scripts (check-freshness, validate-api-sync), AI-Docs section | | 1.0.0 | 2025-11-27 | Initial release | 6:["slug","INTERNAL_DOCS_SYSTEM","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","INTERNAL_DOCS_SYSTEM","c"],{"children":["__PAGE__?{\"slug\":[\"INTERNAL_DOCS_SYSTEM\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","INTERNAL_DOCS_SYSTEM","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":"Internal Documentation System"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","INTERNAL_DOCS_SYSTEM.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/INTERNAL_DOCS_SYSTEM.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":"Internal Documentation System | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Developer guide for documentation tooling, validation scripts, and quality gates."}],["$","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