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
95th percentile
99.9%
Uptime SLA
Monthly target
100
Concurrent Users
Peak capacity
10k
Daily Questions
System limit
### 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*