feat(docs): update markdown formatting to work well with mkdocs
This commit is contained in:
perf3ct
parent
3a797b159f
commit
fdaea4d35b
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
- **📘 User Docs**
|
||||
Installation, configuration, user guide
|
||||
|
||||
- **🔧 Operations**
|
||||
Deployment, monitoring, troubleshooting
|
||||
|
||||
- **💻 Developer**
|
||||
Architecture, development setup, testing
|
||||
|
||||
- **🔌 Integration**
|
||||
API reference, webhooks, extensions
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
- **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
|
||||
|
|
@ -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
|
||||
|
||||
- [🔌 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
|
||||
Loading…
Reference in New Issue