Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: update comprehensive API documentation and project guides

Browse Source 
This commit updates all documentation files throughout the project:

- Updated IMPLEMENTATION_PLAN.md with new implementation details
- Updated PROJECT_GUIDELINES.md with coding standards and practices
- Updated README.md with current project information
- Updated SCREENSHOT_AUTOMATION.md with new automation details
- Added TEST_DATA.md with test fixtures data
- Updated cover_image_serving_plan.md with static URL patterns

Documentation API updates:
- Updated API reference documentation for all endpoints including:
  - Authentication (login, logout, register, refresh_token)
  - Book matching (auto_link, bulk_link, link_book, search)
  - Collections (CRUD operations, shelf mappings, auto-assign rules)
  - Conflicts (bulk operations, resolve/dismiss)
  - Devices (registration, approval, shelf management)
  - Highlights (create, update, delete, get)
  - Kobo sync (bookmark, markup, initialization, sync)
  - KOReader sync (library, metadata, bookmarks, progress)
  - Libraries (CRUD, folders, media items, stats)
  - Media items (bulk operations, CRUD)
  - Notes (CRUD operations)
  - OPDS (acquisition, feeds, publication)
  - Progress (reading progress tracking)
  - Queue (device queue management)
  - Ratings (star ratings)
  - Scanner (watch mode, scan operations)
  - Sync protocols (Kobo, KOReader)
  - Users (profile, password, admin operations)
  - WebSocket protocols

- Updated user guides (admin, dashboard, settings, sync)
- Updated device setup guides (Kobo, KOReader)
- Updated developer guides (testing, contributing, operations)
- Updated scripts/README.md
This commit is contained in:
john-okeefe
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer/api/scanner/get_scan_status.md
+18 -18
View File
@@ -7,15 +7,15 @@ Get the status of a specific scan job.
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| jobId | string (UUID) | Yes | Scan job UUID |
| Parameter | Type | Required | Description |
| --------- | ------------- | -------- | ------------- |
| jobId | string (UUID) | Yes | Scan job UUID |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token (must have admin role) |
| Header | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------- |
| Authorization | string | Yes | Bearer token (must have admin role) |
### Example Request
@@ -52,18 +52,18 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Status Values
| Status | Description |
|--------|-------------|
| pending | Job is queued |
| in_progress | Job is currently running |
| completed | Job completed successfully |
| failed | Job failed with errors |
| cancelled | Job was cancelled |
| Status | Description |
| ----------- | -------------------------- |
| pending | Job is queued |
| in_progress | Job is currently running |
| completed | Job completed successfully |
| failed | Job failed with errors |
| cancelled | Job was cancelled |
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Job not found |
| Code | Description |
| ---- | ----------------------------------- |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Job not found |
docs/developer/api/scanner/get_watch_mode_status.md
+18 -21
View File
@@ -7,15 +7,15 @@ Get the watch mode status for a library.
## Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to check |
| Parameter | Type | Required | Description |
| ---------- | ------------- | -------- | --------------------- |
| library_id | string (UUID) | Yes | Library UUID to check |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | Yes | Bearer token (must have admin role) |
| Header | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------- |
| Authorization | string | Yes | Bearer token (must have admin role) |
### Example Request
@@ -31,10 +31,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
"library_id": "uuid",
"status": "watching",
"started_at": "2026-02-08T10:00:00Z",
"watched_folders": [
"/path/to/library/folder1",
"/path/to/library/folder2"
],
"watched_folders": ["/path/to/library/folder1", "/path/to/library/folder2"],
"stats": {
"files_detected": 15,
"files_processed": 12,
@@ -46,17 +43,17 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
## Status Values
| Status | Description |
|--------|-------------|
| watching | Watch mode is active |
| stopped | Watch mode is not active |
| error | Watch mode encountered an error |
| Status | Description |
| -------- | ------------------------------- |
| watching | Watch mode is active |
| stopped | Watch mode is not active |
| error | Watch mode encountered an error |
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Missing library_id parameter |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| Code | Description |
| ---- | ----------------------------------- |
| 400 | Missing library_id parameter |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
docs/developer/api/scanner/overview.md
+38 -19
View File
@@ -5,16 +5,19 @@ The Bookhoard scanner provides comprehensive library management for ebooks, comi
## Scanner Types
### Manual Scanning
- **One-time scan**: On-demand scanning of library folders
- **Progress tracking**: Real-time status updates with file-by-file progress
- **Error reporting**: Detailed logs of failed files with error messages
### Automated Scanner
- **Periodic scanning**: Configurable interval-based background scanning
- **Automatic discovery**: Detects new files without manual intervention
- **Resource-efficient**: Minimizes system impact with smart scheduling
### Watch Mode
- **Real-time monitoring**: Instant detection of file system changes
- **Event-driven**: Processes files immediately upon addition/modification
- **Platform support**: Works with inotify (Linux), FSEvents (macOS), and ReadDirectoryChangesW (Windows)
@@ -22,36 +25,41 @@ The Bookhoard scanner provides comprehensive library management for ebooks, comi
## Supported Formats
### Ebooks
| Format | Extensions |
|--------|------------|
| EPUB | `.epub` |
| PDF | `.pdf` |
| Kindle | `.mobi`, `.azw`, `.azw3` |
| Text | `.txt`, `.rtf` |
| Document | `.doc`, `.docx` |
| Other | `.lit`, `.fb2`, `.pdb` |
| Format | Extensions |
| -------- | ------------------------ |
| EPUB | `.epub` |
| PDF | `.pdf` |
| Kindle | `.mobi`, `.azw`, `.azw3` |
| Text | `.txt`, `.rtf` |
| Document | `.doc`, `.docx` |
| Other | `.lit`, `.fb2`, `.pdb` |
### Comics
| Format | Extensions | Archive Type |
|--------|------------|--------------|
| Comic Book ZIP | `.cbz` | ZIP |
| Comic Book RAR | `.cbr` | RAR |
| Comic Book 7z | `.cb7` | 7-Zip |
| Comic Book TAR | `.cbt` | TAR |
| PDF Comics | `.pdf` | PDF |
| Format | Extensions | Archive Type |
| -------------- | ---------- | ------------ |
| Comic Book ZIP | `.cbz` | ZIP |
| Comic Book RAR | `.cbr` | RAR |
| Comic Book 7z | `.cb7` | 7-Zip |
| Comic Book TAR | `.cbt` | TAR |
| PDF Comics | `.pdf` | PDF |
### Manga
| Format | Extensions | Notes |
|--------|------------|-------|
| Comic Archives | `.cbz`, `.cbr` | Same as comics |
| Image Files | `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp` | Individual pages |
| Format | Extensions | Notes |
| -------------- | ------------------------------------------------ | ---------------- |
| Comic Archives | `.cbz`, `.cbr` | Same as comics |
| Image Files | `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp` | Individual pages |
## Metadata Extraction
### Comic Archives (.cbz, .cbr, .cb7, .cbt)
The scanner automatically extracts metadata from comic archives:
**ComicInfo.xml Support:**
- Series title
- Issue number
- Publisher
@@ -61,11 +69,13 @@ The scanner automatically extracts metadata from comic archives:
- Cover image extraction
**Fallback Metadata:**
- Filename parsing
- Archive structure analysis
- Page count detection
### Manga Processing
- **Archive-based**: Processes .cbz/.cbr files like comics
- **Image-based**: Handles directories of sequential images
- **Chapter detection**: Identifies chapter/volume numbers from filenames
@@ -74,21 +84,25 @@ The scanner automatically extracts metadata from comic archives:
## Scanner Features
### Smart Deduplication
- SHA256 hash calculation for all files
- Automatic duplicate detection and skipping
- Efficient incremental updates
### Library Type Awareness
- Format filtering based on library type
- Type-specific metadata extraction
- Appropriate thumbnail generation
### Error Handling
- Continues on individual file errors
- Detailed error reporting in scan status
- Failed file tracking for retry
### Progress Tracking
- Total files vs. processed files
- Percentage completion
- Added, updated, and failed file counts
@@ -97,11 +111,13 @@ The scanner automatically extracts metadata from comic archives:
## Performance Considerations
### Large Libraries
- **Scanning speed**: Processes hundreds of files per second
- **Memory usage**: Streaming metadata extraction
- **Database efficiency**: Batch inserts and updates
### Resource Limits
- **Configurable intervals**: Prevent excessive scanning
- **Rate limiting**: Watch mode debounce settings
- **Admin controls**: Start/stop operations as needed
@@ -109,6 +125,7 @@ The scanner automatically extracts metadata from comic archives:
## Usage Examples
### Create and Scan a Comic Library
```json
POST /api/libraries
{
@@ -125,6 +142,7 @@ POST /api/scanner/scan
```
### Enable Watch Mode for Manga
```json
POST /api/scanner/watch/start
{
@@ -133,6 +151,7 @@ POST /api/scanner/watch/start
```
### Check Scan Progress
```http
GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000
```
docs/developer/api/scanner/scan_library.md
+11 -11
View File
@@ -8,11 +8,11 @@ Initiate a one-time scan of a library for ebooks, manga, or comics.
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
| recursive | boolean | No | Scan subdirectories recursively (default: true) |
| force | boolean | No | Force rescan of existing files (default: false) |
| Field | Type | Required | Description |
| ---------- | ------------- | -------- | --------------------------------------------------------- |
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
| recursive | boolean | No | Scan subdirectories recursively (default: true) |
| force | boolean | No | Force rescan of existing files (default: false) |
## Supported Formats
@@ -47,9 +47,9 @@ The scanner automatically detects and processes files based on the library type:
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| Code | Description |
| ---- | ----------------------------------- |
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
docs/developer/api/scanner/start_scanner.md
+11 -11
View File
@@ -8,10 +8,10 @@ Start the automated background scanner for a library. Supports ebook, manga, and
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
| interval_seconds | integer | No | Scan interval in seconds (default: 3600, min: 300) |
| Field | Type | Required | Description |
| ---------------- | ------------- | -------- | --------------------------------------------------------- |
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
| interval_seconds | integer | No | Scan interval in seconds (default: 3600, min: 300) |
## Supported Library Types
@@ -41,10 +41,10 @@ Start the automated background scanner for a library. Supports ebook, manga, and
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data or interval too low |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 409 | Scanner already running for this library |
| Code | Description |
| ---- | ---------------------------------------- |
| 400 | Invalid request data or interval too low |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 409 | Scanner already running for this library |
docs/developer/api/scanner/start_watch_mode.md
+11 -10
View File
@@ -8,13 +8,14 @@ Start watch mode for a library to automatically detect and process new/modified
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to watch (supports ebooks, manga, and comics) |
| Field | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------------------------------------------------- |
| library_id | string (UUID) | Yes | Library UUID to watch (supports ebooks, manga, and comics) |
## Watch Mode Features
Watch mode automatically detects and processes:
- **New files** added to library folders
- **Modified files** that have been updated
- **Format-specific metadata extraction** for comics (.cbz, .cbr) and manga
@@ -41,10 +42,10 @@ Watch mode automatically detects and processes:
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 409 | Watch mode already active for this library |
| Code | Description |
| ---- | ------------------------------------------ |
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 409 | Watch mode already active for this library |
docs/developer/api/scanner/stop_scanner.md
+10 -10
View File
@@ -8,9 +8,9 @@ Stop the automated background scanner for a library.
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to stop scanning |
| Field | Type | Required | Description |
| ---------- | ------------- | -------- | ----------------------------- |
| library_id | string (UUID) | Yes | Library UUID to stop scanning |
### Example Request
@@ -32,10 +32,10 @@ Stop the automated background scanner for a library.
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 400 | Scanner not running for this library |
| Code | Description |
| ---- | ------------------------------------ |
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 400 | Scanner not running for this library |
docs/developer/api/scanner/stop_watch_mode.md
+10 -10
View File
@@ -8,9 +8,9 @@ Stop watch mode for a library.
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| library_id | string (UUID) | Yes | Library UUID to stop watching |
| Field | Type | Required | Description |
| ---------- | ------------- | -------- | ----------------------------- |
| library_id | string (UUID) | Yes | Library UUID to stop watching |
### Example Request
@@ -32,10 +32,10 @@ Stop watch mode for a library.
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 400 | Watch mode not active for this library |
| Code | Description |
| ---- | -------------------------------------- |
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have admin privileges |
| 404 | Library not found |
| 400 | Watch mode not active for this library |