--- title: "Ask Your Docs - Technical Specification" id: "ask-your-docs-technical-spec" project: "Deep Space Exploration Project Translation Publication" url: "https://hedronlabs.clickhelp.co/articles/deep-space-exploration-project-translation-publication/ask-your-docs-technical-spec" updated: 2026-04-21T05:42:15Z --- # Ask Your Docs \- Technical Specification # Ask Your Docs Technical Specification **Technical implementation details and system integration guide** Version 1.0 | Engineering Team | June 2025 ## System Architecture ### Component Overview Ask Your Docs integrates with multiple system components to deliver AI-powered content validation: * **Frontend Interface:** React-based UI component in ClickHelp author dashboard * **API Gateway:** Routes requests and handles authentication * **Content Indexer:** Processes and indexes accessible documentation * **AI Service Integration:** External AI provider for natural language processing * **Usage Tracker:** Monitors and enforces daily limits * **Analytics Engine:** Collects usage metrics and performance data ### Data Flow Architecture ``` User Question → Frontend → API Gateway → Content Indexer → AI Service ↓ Analytics ← Usage Tracker ← Response Handler ← AI Response ``` **Security Note:** All communications between components use encrypted channels (HTTPS/TLS 1.3). User content is processed but not permanently stored by external AI services. ## API Specifications ### Core Endpoints POST /api/v1/ask-your-docs/question Content-Type: application/json Authorization: Bearer {user\_token} \*\*Request Payload:\*\* { "question": "How do I install the software?", "project\_context": "all", // or specific project ID "include\_drafts": true, "max\_context\_length": 4000 } \*\*Response Format:\*\* { "status": "success", "response": { "answer": "To install the software, follow these steps...", "confidence": "high", // high|medium|low "sources": [ { "project\_id": "proj\_123", "topic\_id": "topic\_456", "title": "Installation Guide", "relevance\_score": 0.95 } ], "processing\_time\_ms": 1247 }, "usage": { "questions\_remaining": 8, "daily\_limit": 10, "reset\_time": "2025-06-17T00:00:00Z" }, "metadata": { "request\_id": "req\_789abc", "ai\_model\_version": "gpt-4-turbo", "content\_index\_version": "v2.1.3" } } ### Administrative Endpoints GET /api/v1/admin/ask-your-docs/settings Authorization: Bearer {admin\_token} POST /api/v1/admin/ask-your-docs/enable Content-Type: application/json Authorization: Bearer {admin\_token} { "accept\_ai\_terms": true, "terms\_version": "v1.2" } GET /api/v1/admin/ask-your-docs/analytics Authorization: Bearer {admin\_token} Query Parameters: - start\_date: 2025-06-01 - end\_date: 2025-06-16 - group\_by: day|week|month ## Database Schema ### Core Tables | Table | Purpose | Key Fields | Indexes | | --- | --- | --- | --- | | `ayd_requests` | Log all user questions and responses | user\_id, question\_hash, response\_json, created\_at | user\_id, created\_at, question\_hash | | `ayd_usage_limits` | Track daily usage per user | user\_id, date, question\_count, limit\_value | user\_id + date (unique) | | `ayd_settings` | Portal-level configuration | portal\_id, is\_enabled, ai\_terms\_accepted, settings\_json | portal\_id (unique) | | `ayd_content_index` | Searchable content metadata | content\_id, project\_id, content\_hash, indexed\_at | content\_id, project\_id, content\_hash | ### Usage Analytics Schema { "portal\_id": "portal\_123", "event\_type": "ayd:request", "timestamp": "2025-06-16T14:30:15Z", "user\_id": "user\_456", "metadata": { "question\_length": 45, "response\_confidence": "high", "processing\_time\_ms": 1247, "content\_sources\_count": 3, "ai\_model": "gpt-4-turbo" } } ## Integration Components ### Content Indexing Service #### Indexing Pipeline * **Trigger:** Content save, publish, or manual reindex * **Processing:** Extract text, metadata, and structure * **Storage:** Vector embeddings for semantic search * **Update Frequency:** Real-time for drafts, batch for published content \*\*Content Processing Rules:\*\* | Content Type | Processing Method | Accessibility | Update Trigger | | --- | --- | --- | --- | | Draft Topics | Full text extraction + metadata | Author only | On save | | Published Topics | Full text + structured content | All authorized users | On publish | | Private Projects | Permission-aware indexing | Project members only | Permission change + content update | | Restricted Content | Metadata only | Restricted users | Access level change | ### AI Service Integration **External Dependency:** Ask Your Docs relies on third-party AI services. Monitor service health and implement fallback mechanisms for degraded performance. \*\*Service Configuration:\*\* { "ai\_provider": "openai", "model": "gpt-4-turbo", "max\_tokens": 4096, "temperature": 0.1, "timeout\_seconds": 30, "retry\_attempts": 3, "fallback\_models": ["gpt-3.5-turbo", "claude-3-sonnet"] } ## Performance Specifications ### System Requirements < 3s Response Time 99.9% Uptime SLA 100 Concurrent Users 10k Daily Questions ### Performance Monitoring \*\*Key Metrics to Track:\*\* | Metric | Threshold | Alert Level | Response | | --- | --- | --- | --- | | Average Response Time | > 5 seconds | Warning | Check AI service performance | | Error Rate | > 5% | Critical | Investigate API gateway and AI service | | Content Index Lag | > 10 minutes | Warning | Check indexing service health | | Daily Usage Spike | > 150% normal | Info | Monitor for abuse patterns | ## Security Implementation ### Data Protection #### Privacy Controls * **Data Minimization:** Only relevant content excerpts sent to AI service * **No Persistent Storage:** AI provider does not retain user data * **Access Controls:** Respect existing content permissions * **Audit Logging:** All requests logged for compliance ### Authentication and Authorization \*\*Security Flow:\*\* ``` User Request → JWT Validation → Permission Check → Content Filter → AI Service ↓ Audit Log ← Response Filter ← AI Response ``` \*\*Content Access Rules:\*\* { "access\_matrix": { "draft\_content": ["author", "project\_collaborators"], "published\_content": ["all\_portal\_users"], "private\_projects": ["project\_members\_only"], "restricted\_content": ["explicit\_permissions\_required"] } } ## Configuration Management ### Environment Variables | Variable | Description | Default | Required | | --- | --- | --- | --- | | `AYD_ENABLED` | Global feature toggle | false | Yes | | `AYD_DAILY_LIMIT` | Default questions per user per day | 10 | No | | `AYD_AI_PROVIDER` | AI service provider | openai | Yes | | `AYD_AI_API_KEY` | AI service authentication | - | Yes | | `AYD_MAX_CONTEXT_LENGTH` | Maximum content context size | 4000 | No | | `AYD_TIMEOUT_SECONDS` | AI service request timeout | 30 | No | ### Feature Flags { "ayd\_feature\_flags": { "enable\_draft\_content": true, "enable\_cross\_project\_search": true, "enable\_confidence\_scoring": true, "enable\_source\_attribution": true, "enable\_usage\_analytics": true, "show\_promotional\_cta": true, "enable\_question\_suggestions": false } } ## Monitoring and Alerting ### Health Check Endpoints GET /health/ask-your-docs Response: { "status": "healthy", "components": { "api\_gateway": "up", "content\_index": "up", "ai\_service": "up", "database": "up" }, "response\_time\_ms": 145 } ### Logging Configuration \*\*Log Levels and Content:\*\* | Level | Event Type | Data Included | Retention | | --- | --- | --- | --- | | INFO | Successful requests | User ID, response time, confidence | 30 days | | WARN | Slow responses, high usage | Performance metrics, user patterns | 90 days | | ERROR | Failed requests, system errors | Error details, stack traces, context | 1 year | | DEBUG | Development debugging | Full request/response payload | 7 days | ## Troubleshooting Guide ### Common Issues and Resolutions #### High Response Times **Symptoms:** AI responses taking > 10 seconds **Investigation:** * Check AI service status and latency * Monitor content index query performance * Review concurrent request volume **Resolution:** Scale AI service capacity or implement request queuing #### Content Not Found **Symptoms:** AI reports no relevant content for valid questions **Investigation:** * Verify content indexing is current * Check user permissions for content access * Review content quality and structure **Resolution:** Trigger manual reindex or review content organization #### Usage Limit Exceeded **Symptoms:** Users hitting daily limits unexpectedly **Investigation:** * Review usage patterns for unusual spikes * Check for automated/scripted usage * Verify limit configuration is appropriate **Resolution:** Adjust limits or implement rate limiting ### Diagnostic Commands # Check content index status for user curl -H "Authorization: Bearer {admin\_token}" \ /api/v1/admin/ask-your-docs/content-index/{user\_id} # Force content reindex for project curl -X POST -H "Authorization: Bearer {admin\_token}" \ /api/v1/admin/ask-your-docs/reindex/{project\_id} # Test AI service connectivity curl -X POST -H "Authorization: Bearer {admin\_token}" \ /api/v1/admin/ask-your-docs/test-ai-service ## Deployment Procedures ### Feature Rollout Checklist #### Pre-Deployment * ✅ AI service credentials configured * ✅ Database migrations completed * ✅ Feature flags set appropriately * ✅ Monitoring and alerting configured * ✅ Content indexing service deployed #### Deployment * ✅ Deploy backend services * ✅ Deploy frontend components * ✅ Verify health check endpoints * ✅ Test with staging data * ✅ Enable feature for test users #### Post-Deployment * ✅ Monitor error rates and performance * ✅ Verify user access and permissions * ✅ Test full user workflow * ✅ Confirm analytics data collection * ✅ Document any configuration changes ## Maintenance and Updates ### Regular Maintenance Tasks | Task | Frequency | Responsible Team | Dependencies | | --- | --- | --- | --- | | Content Index Optimization | Weekly | DevOps | Low-traffic windows | | Usage Analytics Review | Monthly | Product Team | Analytics dashboard | | AI Model Version Updates | As available | Engineering | AI provider releases | | Security Audit | Quarterly | Security Team | External audit tools | ## Related Documentation ### Technical Resources - [ClickHelp API Documentation](#) - [Content Management System Architecture](#) - [User Authentication and Authorization](#) - [Analytics and Monitoring Setup](#) ### Operational Guides - [Ask Your Docs User Guide](#) - [Ask Your Docs Admin Guide](#) - [Incident Response Procedures](#) - [Performance Optimization Guide](#) --- \*Last updated: June 16, 2025 | Document version: 1.0 | System version: 1.0.0\*