From fdaea4d35ba68ed60601a057f73b253c4cc38746 Mon Sep 17 00:00:00 2001 From: perf3ct Date: Sat, 16 Aug 2025 17:19:51 +0000 Subject: [PATCH] feat(docs): update markdown formatting to work well with mkdocs --- docs/README.md | 42 +++-- docs/advanced-search.md | 3 +- docs/analytics-dashboard-guide.md | 193 ++++++++++++++++------ docs/dev/README.md | 15 +- docs/file-upload-guide.md | 30 +++- docs/health-monitoring-guide.md | 84 +++++++--- docs/index.md | 28 +++- docs/notifications-guide.md | 140 ++++++++++++---- docs/sources-guide.md | 19 ++- docs/swagger-ui-guide.md | 255 ++++++++++++++++++++++-------- docs/user-guide.md | 52 ++++-- 11 files changed, 644 insertions(+), 217 deletions(-) diff --git a/docs/README.md b/docs/README.md index 8e29c7e..f8e85d7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,12 +52,23 @@ wrangler pages deploy site --project-name=readur-docs ## Structure -- `docs/` - Documentation source files (Markdown) -- `mkdocs.yml` - MkDocs configuration -- `requirements.txt` - Python dependencies -- `overrides/` - Theme customizations -- `stylesheets/` - Custom CSS -- `javascripts/` - Custom JavaScript +- `docs/` + Documentation source files (Markdown) + +- `mkdocs.yml` + MkDocs configuration + +- `requirements.txt` + Python dependencies + +- `overrides/` + Theme customizations + +- `stylesheets/` + Custom CSS + +- `javascripts/` + Custom JavaScript ## Writing Documentation @@ -71,11 +82,20 @@ wrangler pages deploy site --project-name=readur-docs We use several markdown extensions for enhanced functionality: -- **Admonitions** - For notes, warnings, tips -- **Code blocks** - With syntax highlighting -- **Tabs** - For grouped content -- **Tables** - For structured data -- **Emoji** - For visual elements +- **Admonitions** + For notes, warnings, tips + +- **Code blocks** + With syntax highlighting + +- **Tabs** + For grouped content + +- **Tables** + For structured data + +- **Emoji** + For visual elements Example: ```markdown diff --git a/docs/advanced-search.md b/docs/advanced-search.md index fb9c51b..629970f 100644 --- a/docs/advanced-search.md +++ b/docs/advanced-search.md @@ -244,8 +244,9 @@ accessed:last-week # Accessed in the last week ### Size Filters **Size Categories**: + - **Small**: < 1MB -- **Medium**: 1MB - 10MB +- **Medium**: 1MB - 10MB - **Large**: 10MB - 50MB - **Very Large**: > 50MB diff --git a/docs/analytics-dashboard-guide.md b/docs/analytics-dashboard-guide.md index 92740a3..98f4aae 100644 --- a/docs/analytics-dashboard-guide.md +++ b/docs/analytics-dashboard-guide.md @@ -12,87 +12,184 @@ Access the Analytics Dashboard through: ## Document Statistics ### Processing Metrics -- **Total Documents** - Complete count of all documents in the system -- **OCR Success Rate** - Percentage of successful text extractions -- **Processing Speed** - Average documents processed per hour/day -- **Storage Usage** - Total disk space used by documents and metadata + +- **Total Documents** + Complete count of all documents in the system + +- **OCR Success Rate** + Percentage of successful text extractions + +- **Processing Speed** + Average documents processed per hour/day + +- **Storage Usage** + Total disk space used by documents and metadata ### Document Types -- **File Format Breakdown** - Distribution of PDF, images, Office docs -- **Source Distribution** - Documents by upload method (manual, WebDAV, S3, local) -- **Size Distribution** - Document size ranges and storage impact -- **Language Detection** - OCR language distribution statistics + +- **File Format Breakdown** + Distribution of PDF, images, Office docs + +- **Source Distribution** + Documents by upload method (manual, WebDAV, S3, local) + +- **Size Distribution** + Document size ranges and storage impact + +- **Language Detection** + OCR language distribution statistics ## Processing Status Overview ### Real-time Status -- **Queue Length** - Current documents awaiting processing -- **Active Jobs** - Documents currently being processed -- **Recent Completions** - Recently finished processing jobs -- **Error Count** - Failed processing attempts requiring attention + +- **Queue Length** + Current documents awaiting processing + +- **Active Jobs** + Documents currently being processed + +- **Recent Completions** + Recently finished processing jobs + +- **Error Count** + Failed processing attempts requiring attention ### Processing History -- **Hourly Trends** - Processing volume over time -- **Daily Patterns** - Peak usage times and quiet periods -- **Success Rates** - Historical OCR and processing reliability -- **Performance Metrics** - Processing speed improvements over time + +- **Hourly Trends** + Processing volume over time + +- **Daily Patterns** + Peak usage times and quiet periods + +- **Success Rates** + Historical OCR and processing reliability + +- **Performance Metrics** + Processing speed improvements over time ## User Activity Analytics ### Usage Patterns -- **Active Users** - Daily/weekly/monthly active user counts -- **Upload Activity** - Document upload frequency by user -- **Search Activity** - Most common search terms and patterns -- **Feature Usage** - Which features are used most frequently + +- **Active Users** + Daily/weekly/monthly active user counts + +- **Upload Activity** + Document upload frequency by user + +- **Search Activity** + Most common search terms and patterns + +- **Feature Usage** + Which features are used most frequently ### Access Patterns -- **Login Statistics** - User authentication frequency -- **Session Duration** - Average time spent in the application -- **Popular Documents** - Most accessed and searched documents -- **Peak Hours** - Busiest times for system usage + +- **Login Statistics** + User authentication frequency + +- **Session Duration** + Average time spent in the application + +- **Popular Documents** + Most accessed and searched documents + +- **Peak Hours** + Busiest times for system usage ## Source Performance ### Sync Statistics -- **Source Health** - Status of all configured data sources -- **Sync Frequency** - How often sources are synchronized -- **Discovery Rate** - New documents found per sync cycle -- **Error Rates** - Failed sync attempts by source type + +- **Source Health** + Status of all configured data sources + +- **Sync Frequency** + How often sources are synchronized + +- **Discovery Rate** + New documents found per sync cycle + +- **Error Rates** + Failed sync attempts by source type ### Source Comparison -- **Volume by Source** - Document counts from each source -- **Performance Metrics** - Sync speed and reliability comparison -- **Storage Usage** - Disk usage by source type -- **Processing Success** - OCR success rates by source + +- **Volume by Source** + Document counts from each source + +- **Performance Metrics** + Sync speed and reliability comparison + +- **Storage Usage** + Disk usage by source type + +- **Processing Success** + OCR success rates by source ## System Performance ### Resource Utilization -- **CPU Usage** - System load over time -- **Memory Usage** - RAM consumption patterns -- **Disk I/O** - Storage read/write activity -- **Network Usage** - Bandwidth utilization for remote sources + +- **CPU Usage** + System load over time + +- **Memory Usage** + RAM consumption patterns + +- **Disk I/O** + Storage read/write activity + +- **Network Usage** + Bandwidth utilization for remote sources ### Health Indicators -- **Uptime Statistics** - System availability metrics -- **Response Times** - API and web interface performance -- **Error Rates** - System error frequency and types -- **Queue Health** - Background job processing efficiency + +- **Uptime Statistics** + System availability metrics + +- **Response Times** + API and web interface performance + +- **Error Rates** + System error frequency and types + +- **Queue Health** + Background job processing efficiency ## Custom Reports ### Report Builder + Create custom analytics reports with: -- **Date Range Selection** - Custom time periods for analysis -- **Metric Selection** - Choose specific statistics to include -- **Filtering Options** - Filter by user, source, document type -- **Export Formats** - Download as PDF, Excel, or CSV + +- **Date Range Selection** + Custom time periods for analysis + +- **Metric Selection** + Choose specific statistics to include + +- **Filtering Options** + Filter by user, source, document type + +- **Export Formats** + Download as PDF, Excel, or CSV ### Scheduled Reports -- **Daily Summaries** - Automated daily statistics via email -- **Weekly Reports** - Comprehensive weekly performance reports -- **Monthly Analytics** - Detailed monthly usage and health reports -- **Custom Schedules** - Configure custom report frequencies + +- **Daily Summaries** + Automated daily statistics via email + +- **Weekly Reports** + Comprehensive weekly performance reports + +- **Monthly Analytics** + Detailed monthly usage and health reports + +- **Custom Schedules** + Configure custom report frequencies ## Data Export diff --git a/docs/dev/README.md b/docs/dev/README.md index 9ebd3cc..369c0e7 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -45,7 +45,14 @@ Please read our [Development Guide](development.md) for: ## 🏷️ Document Categories -- **📘 User Docs**: Installation, configuration, user guide -- **🔧 Operations**: Deployment, monitoring, troubleshooting -- **💻 Developer**: Architecture, development setup, testing -- **🔌 Integration**: API reference, webhooks, extensions \ No newline at end of file +- **📘 User Docs** + Installation, configuration, user guide + +- **🔧 Operations** + Deployment, monitoring, troubleshooting + +- **💻 Developer** + Architecture, development setup, testing + +- **🔌 Integration** + API reference, webhooks, extensions \ No newline at end of file diff --git a/docs/file-upload-guide.md b/docs/file-upload-guide.md index 32480f2..e70bfa7 100644 --- a/docs/file-upload-guide.md +++ b/docs/file-upload-guide.md @@ -4,10 +4,17 @@ Readur provides an intuitive drag-and-drop file upload system that supports mult ## Supported File Types -- **PDF Files** (.pdf) - Direct text extraction and OCR for scanned PDFs -- **Images** (.png, .jpg, .jpeg, .tiff, .bmp, .webp) - Full OCR text extraction -- **Text Files** (.txt, .rtf) - Direct text import -- **Office Documents** (.docx, .doc, .xlsx, .xls, .pptx, .ppt) - Text extraction and OCR +- **PDF Files** (.pdf) + Direct text extraction and OCR for scanned PDFs + +- **Images** (.png, .jpg, .jpeg, .tiff, .bmp, .webp) + Full OCR text extraction + +- **Text Files** (.txt, .rtf) + Direct text import + +- **Office Documents** (.docx, .doc, .xlsx, .xls, .pptx, .ppt) + Text extraction and OCR ## Upload Methods @@ -57,10 +64,17 @@ This enhancement ensures files are correctly identified even when extensions are ## Best Practices -- **File Size**: Keep individual files under 50MB for optimal performance -- **File Names**: Use descriptive names for better organization -- **Batch Size**: Upload 10-20 files at once for best performance -- **Network**: Stable internet connection recommended for large uploads +- **File Size** + Keep individual files under 50MB for optimal performance + +- **File Names** + Use descriptive names for better organization + +- **Batch Size** + Upload 10-20 files at once for best performance + +- **Network** + Stable internet connection recommended for large uploads ## Troubleshooting diff --git a/docs/health-monitoring-guide.md b/docs/health-monitoring-guide.md index 82278cb..f839541 100644 --- a/docs/health-monitoring-guide.md +++ b/docs/health-monitoring-guide.md @@ -41,28 +41,56 @@ Access health information through: ## System Health Metrics ### Performance Indicators -- **CPU Usage** - System load monitoring -- **Memory Usage** - RAM utilization tracking -- **Disk Space** - Storage capacity alerts -- **Queue Length** - Processing backlog size + +- **CPU Usage** + System load monitoring + +- **Memory Usage** + RAM utilization tracking + +- **Disk Space** + Storage capacity alerts + +- **Queue Length** + Processing backlog size ### Processing Health -- **OCR Success Rate** - Text extraction reliability -- **Processing Speed** - Documents per minute -- **Error Rates** - Failed operation tracking -- **Retry Attempts** - Automatic recovery metrics + +- **OCR Success Rate** + Text extraction reliability + +- **Processing Speed** + Documents per minute + +- **Error Rates** + Failed operation tracking + +- **Retry Attempts** + Automatic recovery metrics ## Alert Configuration ### Alert Types -- **Critical** - System failures requiring immediate attention -- **Warning** - Performance degradation or resource limits -- **Info** - Status updates and maintenance notifications + +- **Critical** + System failures requiring immediate attention + +- **Warning** + Performance degradation or resource limits + +- **Info** + Status updates and maintenance notifications ### Notification Methods -- **In-App Notifications** - Real-time dashboard alerts -- **Email Alerts** - Configurable email notifications -- **Webhook Integration** - External system notifications + +- **In-App Notifications** + Real-time dashboard alerts + +- **Email Alerts** + Configurable email notifications + +- **Webhook Integration** + External system notifications ## Health Check Endpoints @@ -98,15 +126,29 @@ GET /api/health/sources/{source_id} ## Troubleshooting ### Common Issues -- **Source Disconnected** - Check network connectivity and credentials -- **High Queue Length** - Scale processing resources or optimize OCR -- **Memory Warnings** - Review document processing batch sizes -- **Disk Space Low** - Clean up temporary files or expand storage + +- **Source Disconnected** + Check network connectivity and credentials + +- **High Queue Length** + Scale processing resources or optimize OCR + +- **Memory Warnings** + Review document processing batch sizes + +- **Disk Space Low** + Clean up temporary files or expand storage ### Recovery Actions -- **Automatic Retry** - Failed operations retry with exponential backoff -- **Graceful Degradation** - System continues operating with reduced functionality -- **Manual Intervention** - Admin tools for resolving complex issues + +- **Automatic Retry** + Failed operations retry with exponential backoff + +- **Graceful Degradation** + System continues operating with reduced functionality + +- **Manual Intervention** + Admin tools for resolving complex issues ## Configuration diff --git a/docs/index.md b/docs/index.md index e433bb0..4329f1a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -111,15 +111,29 @@ graph LR ## Getting Help ### Documentation -- [User Guide](user-guide.md) - Complete feature documentation -- [Configuration Reference](configuration-reference.md) - All environment variables -- [Troubleshooting](s3-troubleshooting.md) - Common issues and solutions -- [Migration Guide](migration-guide.md) - Upgrade and migration procedures + +- [User Guide](user-guide.md) + Complete feature documentation + +- [Configuration Reference](configuration-reference.md) + All environment variables + +- [Troubleshooting](s3-troubleshooting.md) + Common issues and solutions + +- [Migration Guide](migration-guide.md) + Upgrade and migration procedures ### Community & Support -- [GitHub Issues](https://github.com/readur/readur/issues) - Bug reports and feature requests -- [GitHub Discussions](https://github.com/readur/readur/discussions) - Community help -- [Developer Documentation](dev/) - Architecture and development setup + +- [GitHub Issues](https://github.com/readur/readur/issues) + Bug reports and feature requests + +- [GitHub Discussions](https://github.com/readur/readur/discussions) + Community help + +- [Developer Documentation](dev/) + Architecture and development setup ## Latest Updates diff --git a/docs/notifications-guide.md b/docs/notifications-guide.md index 90db057..2294857 100644 --- a/docs/notifications-guide.md +++ b/docs/notifications-guide.md @@ -5,36 +5,76 @@ Readur provides comprehensive real-time notifications to keep you informed about ## Notification Types ### Document Processing -- **OCR Completion** - Text extraction finished for uploaded documents -- **Processing Errors** - Failed OCR or document processing alerts -- **Batch Processing** - Status updates for multiple document uploads -- **Quality Warnings** - Low-quality OCR results requiring attention + +- **OCR Completion** + Text extraction finished for uploaded documents + +- **Processing Errors** + Failed OCR or document processing alerts + +- **Batch Processing** + Status updates for multiple document uploads + +- **Quality Warnings** + Low-quality OCR results requiring attention ### Sync Events -- **Source Sync Complete** - WebDAV, S3, or local folder synchronization finished -- **New Documents Found** - Fresh documents discovered during sync -- **Sync Errors** - Connection issues or permission problems -- **Conflict Resolution** - File conflicts requiring user intervention + +- **Source Sync Complete** + WebDAV, S3, or local folder synchronization finished + +- **New Documents Found** + Fresh documents discovered during sync + +- **Sync Errors** + Connection issues or permission problems + +- **Conflict Resolution** + File conflicts requiring user intervention ### System Status -- **Health Alerts** - System performance warnings or failures -- **Maintenance Windows** - Scheduled maintenance notifications -- **Security Events** - Login attempts, permission changes -- **Storage Warnings** - Disk space or quota limitations + +- **Health Alerts** + System performance warnings or failures + +- **Maintenance Windows** + Scheduled maintenance notifications + +- **Security Events** + Login attempts, permission changes + +- **Storage Warnings** + Disk space or quota limitations ## Notification Delivery ### In-App Notifications -- **Real-time Badge** - Notification counter in the top navigation -- **Notification Panel** - Expandable list of recent alerts -- **Toast Messages** - Immediate pop-up notifications for urgent items -- **Dashboard Widgets** - Status cards showing notification summaries + +- **Real-time Badge** + Notification counter in the top navigation + +- **Notification Panel** + Expandable list of recent alerts + +- **Toast Messages** + Immediate pop-up notifications for urgent items + +- **Dashboard Widgets** + Status cards showing notification summaries ### Email Notifications -- **Immediate Alerts** - Critical system or processing failures -- **Daily Digest** - Summary of processing activity and status -- **Weekly Reports** - System health and usage statistics -- **Custom Triggers** - User-configured alert conditions + +- **Immediate Alerts** + Critical system or processing failures + +- **Daily Digest** + Summary of processing activity and status + +- **Weekly Reports** + System health and usage statistics + +- **Custom Triggers** + User-configured alert conditions ## Notification Settings @@ -45,16 +85,32 @@ Access notification settings through: 3. Configure your preferences for each notification type ### Notification Categories -- **Critical** - System failures, security alerts (always enabled) -- **Important** - Processing errors, sync failures -- **Informational** - Completion notifications, status updates -- **Promotional** - Feature updates, tips (can be disabled) + +- **Critical** + System failures, security alerts (always enabled) + +- **Important** + Processing errors, sync failures + +- **Informational** + Completion notifications, status updates + +- **Promotional** + Feature updates, tips (can be disabled) ### Delivery Preferences -- **In-App Only** - Notifications appear only within Readur -- **Email + In-App** - Notifications sent to both locations -- **Email Only** - Notifications sent only via email -- **Disabled** - No notifications for this category + +- **In-App Only** + Notifications appear only within Readur + +- **Email + In-App** + Notifications sent to both locations + +- **Email Only** + Notifications sent only via email + +- **Disabled** + No notifications for this category ## Advanced Configuration @@ -119,15 +175,29 @@ Send notifications to external systems: ## Managing Notifications ### Notification History -- **View All** - Complete history of notifications -- **Filter by Type** - Show only specific notification categories -- **Search** - Find notifications by content or date -- **Archive** - Mark notifications as read or hide them + +- **View All** + Complete history of notifications + +- **Filter by Type** + Show only specific notification categories + +- **Search** + Find notifications by content or date + +- **Archive** + Mark notifications as read or hide them ### Bulk Actions -- **Mark All Read** - Clear all unread notification badges -- **Delete Old** - Remove notifications older than specified date -- **Export** - Download notification history as CSV or JSON + +- **Mark All Read** + Clear all unread notification badges + +- **Delete Old** + Remove notifications older than specified date + +- **Export** + Download notification history as CSV or JSON ## Troubleshooting diff --git a/docs/sources-guide.md b/docs/sources-guide.md index 4eb632a..881bca8 100644 --- a/docs/sources-guide.md +++ b/docs/sources-guide.md @@ -422,11 +422,20 @@ ws.onmessage = (event) => { Sources are continuously monitored and assigned health scores (0-100): -- **90-100**: ✅ Excellent - No issues detected -- **75-89**: ⚠️ Good - Minor issues or warnings -- **50-74**: ⚠️ Fair - Moderate issues requiring attention -- **25-49**: ❌ Poor - Significant problems -- **0-24**: ❌ Critical - Severe issues, manual intervention required +- **90-100**: ✅ Excellent + No issues detected + +- **75-89**: ⚠️ Good + Minor issues or warnings + +- **50-74**: ⚠️ Fair + Moderate issues requiring attention + +- **25-49**: ❌ Poor + Significant problems + +- **0-24**: ❌ Critical + Severe issues, manual intervention required ### Health Checks diff --git a/docs/swagger-ui-guide.md b/docs/swagger-ui-guide.md index 3cf9a2e..15dde67 100644 --- a/docs/swagger-ui-guide.md +++ b/docs/swagger-ui-guide.md @@ -12,48 +12,104 @@ Readur includes built-in Swagger UI for interactive API documentation and testin ## API Documentation Features ### Endpoint Explorer -- **Complete API Reference** - All REST endpoints with detailed descriptions -- **Request/Response Examples** - Sample data for every endpoint -- **Parameter Details** - Required and optional parameters with types -- **Authentication Info** - JWT token requirements and usage + +- **Complete API Reference** + All REST endpoints with detailed descriptions + +- **Request/Response Examples** + Sample data for every endpoint + +- **Parameter Details** + Required and optional parameters with types + +- **Authentication Info** + JWT token requirements and usage ### Interactive Testing -- **Try It Out** - Execute API calls directly from the documentation -- **Real Data** - Test with your actual Readur data and configuration -- **Response Validation** - See actual responses and status codes -- **Error Handling** - View error responses and troubleshooting info + +- **Try It Out** + Execute API calls directly from the documentation + +- **Real Data** + Test with your actual Readur data and configuration + +- **Response Validation** + See actual responses and status codes + +- **Error Handling** + View error responses and troubleshooting info ## API Categories ### Authentication -- **Login/Logout** - User authentication endpoints -- **Token Management** - JWT token refresh and validation -- **User Registration** - New user account creation -- **Password Reset** - Password recovery workflows + +- **Login/Logout** + User authentication endpoints + +- **Token Management** + JWT token refresh and validation + +- **User Registration** + New user account creation + +- **Password Reset** + Password recovery workflows ### Document Management -- **Upload Documents** - Single and batch file upload endpoints -- **Document Retrieval** - Get document metadata and content -- **Document Search** - Full-text search with various modes -- **Document Operations** - Update, delete, and organize documents + +- **Upload Documents** + Single and batch file upload endpoints + +- **Document Retrieval** + Get document metadata and content + +- **Document Search** + Full-text search with various modes + +- **Document Operations** + Update, delete, and organize documents ### User Management -- **User CRUD** - Create, read, update, delete user accounts -- **Role Management** - Assign and modify user roles -- **Permission Control** - Manage access rights and restrictions -- **User Preferences** - Personal settings and configurations + +- **User CRUD** + Create, read, update, delete user accounts + +- **Role Management** + Assign and modify user roles + +- **Permission Control** + Manage access rights and restrictions + +- **User Preferences** + Personal settings and configurations ### Source Management -- **Source Configuration** - WebDAV, S3, and local folder setup -- **Sync Operations** - Manual and automated synchronization -- **Source Health** - Status monitoring and health checks -- **Source Statistics** - Usage metrics and performance data + +- **Source Configuration** + WebDAV, S3, and local folder setup + +- **Sync Operations** + Manual and automated synchronization + +- **Source Health** + Status monitoring and health checks + +- **Source Statistics** + Usage metrics and performance data ### System Administration -- **Health Monitoring** - System status and performance metrics -- **Analytics Data** - Usage statistics and reporting endpoints -- **Configuration** - System settings and environment variables -- **Maintenance** - Backup, cleanup, and administrative tasks + +- **Health Monitoring** + System status and performance metrics + +- **Analytics Data** + Usage statistics and reporting endpoints + +- **Configuration** + System settings and environment variables + +- **Maintenance** + Backup, cleanup, and administrative tasks ## Authentication in Swagger UI @@ -65,58 +121,122 @@ Readur includes built-in Swagger UI for interactive API documentation and testin 5. **Test Endpoints** - All authenticated endpoints now work with your credentials ### Token Management -- **Token Expiry** - Tokens expire after a configured time period -- **Refresh Tokens** - Use refresh token endpoint to get new access tokens -- **Logout** - Invalidate tokens using the logout endpoint -- **Multiple Sessions** - Each browser session needs its own token + +- **Token Expiry** + Tokens expire after a configured time period + +- **Refresh Tokens** + Use refresh token endpoint to get new access tokens + +- **Logout** + Invalidate tokens using the logout endpoint + +- **Multiple Sessions** + Each browser session needs its own token ## Best Practices ### Development Usage -- **Test First** - Use Swagger UI to test API endpoints before implementing -- **Validate Responses** - Check response formats match your expectations -- **Error Scenarios** - Test error conditions and edge cases -- **Performance Testing** - Monitor response times for optimization + +- **Test First** + Use Swagger UI to test API endpoints before implementing + +- **Validate Responses** + Check response formats match your expectations + +- **Error Scenarios** + Test error conditions and edge cases + +- **Performance Testing** + Monitor response times for optimization ### Production Considerations -- **Access Control** - Swagger UI respects the same authentication as the main app -- **Rate Limiting** - API rate limits apply to Swagger UI requests -- **Logging** - All API calls from Swagger UI are logged normally -- **Security** - Use HTTPS in production for secure token transmission + +- **Access Control** + Swagger UI respects the same authentication as the main app + +- **Rate Limiting** + API rate limits apply to Swagger UI requests + +- **Logging** + All API calls from Swagger UI are logged normally + +- **Security** + Use HTTPS in production for secure token transmission ## Common Use Cases ### Frontend Development -- **API Integration** - Test endpoints before implementing in your frontend -- **Data Formats** - Understand expected request/response formats -- **Error Handling** - Learn about error codes and messages -- **Feature Testing** - Validate new features work as expected + +- **API Integration** + Test endpoints before implementing in your frontend + +- **Data Formats** + Understand expected request/response formats + +- **Error Handling** + Learn about error codes and messages + +- **Feature Testing** + Validate new features work as expected ### System Integration -- **Third-party Tools** - Test integration with external systems -- **Automation Scripts** - Develop scripts using API documentation -- **Monitoring Systems** - Integrate health check endpoints -- **Data Migration** - Use bulk operations for data import/export + +- **Third-party Tools** + Test integration with external systems + +- **Automation Scripts** + Develop scripts using API documentation + +- **Monitoring Systems** + Integrate health check endpoints + +- **Data Migration** + Use bulk operations for data import/export ### Troubleshooting -- **Debug Issues** - Test API calls to isolate problems -- **Validate Permissions** - Check if user roles have correct access -- **Network Testing** - Verify connectivity and response times -- **Data Verification** - Confirm data integrity and processing status + +- **Debug Issues** + Test API calls to isolate problems + +- **Validate Permissions** + Check if user roles have correct access + +- **Network Testing** + Verify connectivity and response times + +- **Data Verification** + Confirm data integrity and processing status ## Advanced Features ### Custom Headers -- **Request Customization** - Add custom headers to API requests -- **Content-Type** - Specify different content types for uploads -- **User-Agent** - Set custom user agent strings -- **Cache Control** - Control caching behavior for responses + +- **Request Customization** + Add custom headers to API requests + +- **Content-Type** + Specify different content types for uploads + +- **User-Agent** + Set custom user agent strings + +- **Cache Control** + Control caching behavior for responses ### Bulk Operations -- **Batch Uploads** - Test multiple file uploads simultaneously -- **Bulk Updates** - Update multiple documents or users at once -- **Mass Operations** - Perform administrative tasks in bulk -- **Data Export** - Export large datasets via API + +- **Batch Uploads** + Test multiple file uploads simultaneously + +- **Bulk Updates** + Update multiple documents or users at once + +- **Mass Operations** + Perform administrative tasks in bulk + +- **Data Export** + Export large datasets via API ## Configuration Options @@ -138,7 +258,14 @@ SWAGGER_RATE_LIMIT=1000 ## Security Considerations -- **Authentication Required** - Swagger UI requires the same login as the main application -- **Role-Based Access** - API endpoints respect user role permissions -- **Audit Logging** - All API calls are logged for security monitoring -- **Token Security** - JWT tokens should be kept secure and not shared \ No newline at end of file +- **Authentication Required** + Swagger UI requires the same login as the main application + +- **Role-Based Access** + API endpoints respect user role permissions + +- **Audit Logging** + All API calls are logged for security monitoring + +- **Token Security** + JWT tokens should be kept secure and not shared \ No newline at end of file diff --git a/docs/user-guide.md b/docs/user-guide.md index a73928f..b93bf63 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -392,20 +392,46 @@ Readur supports both local and OIDC users in the same installation: ## Next Steps ### Explore Advanced Features -- [🔗 Sources Guide](sources-guide.md) - Set up WebDAV, Local Folder, and S3 synchronization -- [🔎 Advanced Search](advanced-search.md) - Master search modes, syntax, and optimization -- [🏷️ Labels & Organization](labels-and-organization.md) - Implement effective document organization -- [👥 User Management](user-management-guide.md) - Configure authentication and user administration -- [🔐 OIDC Setup](oidc-setup.md) - Integrate with enterprise identity providers + +- [🔗 Sources Guide](sources-guide.md) + Set up WebDAV, Local Folder, and S3 synchronization + +- [🔎 Advanced Search](advanced-search.md) + Master search modes, syntax, and optimization + +- [🏷️ Labels & Organization](labels-and-organization.md) + Implement effective document organization + +- [👥 User Management](user-management-guide.md) + Configure authentication and user administration + +- [🔐 OIDC Setup](oidc-setup.md) + Integrate with enterprise identity providers ### System Administration -- [📦 Installation Guide](installation.md) - Full installation and setup instructions -- [🔧 Configuration](configuration.md) - Environment variables and advanced configuration -- [🚀 Deployment Guide](deployment.md) - Production deployment with SSL and monitoring -- [📁 Watch Folder Guide](WATCH_FOLDER.md) - Legacy folder watching setup + +- [📦 Installation Guide](installation.md) + Full installation and setup instructions + +- [🔧 Configuration](configuration.md) + Environment variables and advanced configuration + +- [🚀 Deployment Guide](deployment.md) + Production deployment with SSL and monitoring + +- [📁 Watch Folder Guide](WATCH_FOLDER.md) + Legacy folder watching setup ### Development and Integration -- [🔌 API Reference](api-reference.md) - REST API for automation and integration -- [🏗️ Developer Documentation](dev/) - Architecture and development setup -- [🔍 OCR Optimization](dev/OCR_OPTIMIZATION_GUIDE.md) - Improve OCR performance -- [📊 Queue Architecture](dev/QUEUE_IMPROVEMENTS.md) - Background processing optimization \ No newline at end of file + +- [🔌 API Reference](api-reference.md) + REST API for automation and integration + +- [🏗️ Developer Documentation](dev/) + Architecture and development setup + +- [🔍 OCR Optimization](dev/OCR_OPTIMIZATION_GUIDE.md) + Improve OCR performance + +- [📊 Queue Architecture](dev/QUEUE_IMPROVEMENTS.md) + Background processing optimization \ No newline at end of file