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

docs: restructure documentation and update guidelines

Browse Source 
- Update PROJECT_GUIDELINES.md to reflect current architecture (Hybrid SSR)
- Integrate service layer and SSR rules into existing sections
- Update README.md paths to match new docs structure (docs/developer/api, docs/user/devices)
- Remove redundant README.md files from bruno/ directories
- Update bruno/collection.bru documentation to current API standard
- Fix architectural pattern description from API-driven to Hybrid SSR
This commit is contained in:
john-okeefe
2026-02-02 16:45:59 -05:00
parent 253f56399d
commit 155b58aef6
6 changed files with 221 additions and 770 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bruno/sidecar/README.md
-243
View File
@@ -1,243 +0,0 @@
# Phase 8: Sidecar Configuration System - API Documentation
## Overview
This document describes the sidecar configuration system that enables easy device setup for Kobo and KOReader devices.
## What is a Sidecar File?
A sidecar file (`.bookhoard.json`) is a configuration file that contains all the information a device needs to connect to Bookhoard, including:
- OPDS catalog URL for wireless book browsing
- Sync API endpoints for progress sync
- Book inventory with SHA-256 hashes
- Collection metadata with shelf mappings
## Authentication
All endpoints require authentication:
- User endpoints: Use user JWT token (Authorization: Bearer {{user_token}})
- Admin endpoints: Use admin JWT token (Authorization: Bearer {{admin_token}})
## Endpoints
### 1. Get Device Sidecar Config
**Endpoint**: `GET /api/devices/:device_id/sidecar`
**Description**: Returns sidecar configuration for a device as JSON.
**Request Headers**:
```
Authorization: Bearer {{user_token}}
```
**Response** (200 OK):
```json
{
"version": "1.0",
"bookhoard": {
"opds_catalog": "http://192.168.1.100:8765/opds/devices/kobo-id/catalog",
"sync_api": "http://192.168.1.100:8765/api/sync/kobo",
"opds_base_url": "http://192.168.1.100:8765/opds",
"api_base_url": "http://192.168.1.100:8765/api",
"device_id": "kobo-device-uuid",
"device_token": "dev_xxxxx..."
},
"books": {
"sha256:abc123...": {
"bookhoard_uuid": "uuid-123",
"title": "The Hobbit",
"author": "J.R.R. Tolkien",
"available_formats": ["epub", "kepub"],
"sha256": "abc123...",
"file_path": "/path/to/book.epub"
}
},
"collections": [
{
"name": "Sci-Fi",
"shelf_mapping": "Science Fiction",
"book_ids": ["uuid-1", "uuid-2", "uuid-3"]
}
],
"opds_enabled": true,
"sidecar_enabled": true,
"last_updated": "2026-01-31T12:00:00Z"
}
```
### 2. Download Device Sidecar File
**Endpoint**: `GET /api/devices/:device_id/sidecar/download`
**Description**: Downloads a `.bookhoard.json` configuration file for device setup.
**Request Headers**:
```
Authorization: Bearer {{user_token}}
```
**Response** (200 OK):
```
Content-Type: application/json
Content-Disposition: attachment; filename="MyKoboClara.bookhoard.json"
```
File contains formatted JSON (pretty-printed) suitable for:
- Manual device configuration
- Backup and restore
- Transfer via USB
### 3. Get System Configuration
**Endpoint**: `GET /api/system/config`
**Description**: Returns system-wide configuration settings (admin only).
**Request Headers**:
```
Authorization: Bearer {{admin_token}}
```
**Response** (200 OK):
```json
{
"base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookhoard.example.com/api"
}
```
### 4. Update System Configuration
**Endpoint**: `PUT /api/system/config`
**Description**: Updates system-wide configuration settings (admin only).
**Request Headers**:
```
Authorization: Bearer {{admin_token}}
Content-Type: application/json
```
**Request Body**:
```json
{
"base_url": "https://bookhoard.example.com",
"opds_base_url": "https://bookhoard.example.com/opds",
"api_base_url": "https://bookhoard.example.com/api"
}
```
**Response** (200 OK):
```json
{
"status": "success",
"message": "System configuration updated"
}
```
## Sidecar File Format
### Version
Always "1.0" - enables future format changes
### Bookhoard Section
Contains device connection information:
- **opds_catalog**: Full URL to device's OPDS catalog
- **sync_api**: Sync API endpoint
- **opds_base_url**: Base URL for all OPDS operations
- **api_base_url**: Base URL for all API operations
- **device_id**: Device's unique identifier
- **device_token**: Device authentication token
### Books Section
Map of book identifiers to book metadata:
- **Key**: SHA-256 hash (preferred) or Bookhoard UUID
- **bookhoard_uuid**: Canonical Bookhoard UUID
- **title**: Book title
- **author**: Book author
- **available_formats**: Array of formats ("epub", "kepub")
- **sha256**: SHA-256 hash of book file
- **file_path**: Original file path
### Collections Section
Array of collection definitions:
- **name**: Collection name in Bookhoard
- **shelf_mapping**: Device-specific shelf name (e.g., "Science Fiction")
- **book_ids**: Array of Bookhoard UUIDs in collection
## Device Setup Workflow
### Kobo E-Reader
1. **Download Configuration**
- Log into Bookhoard web UI
- Navigate to Device Management
- Click "Download Configuration" for your Kobo device
- File saves as `MyKoboClara.bookhoard.json`
2. **Manual Configuration** (if needed)
- Copy `.bookhoard.json` to Kobo device
- Kobo can import configuration automatically
3. **OPDS Setup** (Recommended)
- Use `opds_catalog` URL from sidecar
- Add as new content catalog in Kobo settings
- Browse and download books wirelessly
### KOReader
1. **Download Configuration**
- Same process as Kobo above
2. **Configure Wireless Sync**
- In KOReader, set Calibre wireless URL to `sync_api` from sidecar
- Enable password and use `device_token`
- Set sync frequency to desired interval
## Environment Variables
Set these in your Bruno collection:
```json
{
"base_url": "http://localhost:8765/api",
"user_token": "your-user-jwt-token",
"admin_token": "your-admin-jwt-token",
"device_id": "uuid-of-device"
}
```
## Error Codes
- `200`: Success
- `400`: Bad Request (invalid device ID, invalid JSON)
- `401`: Unauthorized (missing or invalid token)
- `403`: Forbidden (admin access required)
- `404`: Not Found (device not found)
- `500`: Internal Server Error (database error, generation failure)
## Benefits
1. **Easy Setup**: One file contains all configuration
2. **No Manual Entry**: URLs and tokens pre-populated
3. **SHA-256 Matching**: Reliable book identification
4. **Collection Sync**: Shelf mappings included
5. **Backup/Restore**: Save and transfer device configs
6. **Offline Configuration**: Configure devices without network access initially
## Testing Scenarios
### Scenario 1: New Kobo Device
1. Register Kobo device in Bookhoard
2. Download sidecar configuration
3. Add OPDS catalog URL from sidecar to Kobo
4. Browse and download books wirelessly
5. Progress syncs automatically
### Scenario 2: Device Re-configuration
1. Download current sidecar file
2. Update system configuration if needed
3. Re-download sidecar with new settings
4. Re-configure device with updated file
### Scenario 3: Collection Management
1. Create collections in Bookhoard
2. Set up device-specific shelf mappings
3. Sidecar automatically includes collection info
4. Device shelves reflect collection structure