john-okeefe
da33e2c126
Updated Carousel Dashboard documentation to reflect finalized architecture decisions and resolve discrepancies between plan and verification checklist. ## CAROUSEL_DASHBOARD_PLAN.md Changes ### Added Phase 4.5: Collections Preview Endpoint - Documented why preview endpoint is required (web UI + mobile apps) - Explained why client-side preview is a bad idea (download entire library, code duplication, maintenance nightmare) - Added full PreviewCollection handler implementation - Added Bruno test specification ### Enhanced Phase 7: Router Registration & Config Setup - Renamed from "Router Registration" to "Router Registration & Config Setup" - Added Step 1: Update router.go Config struct with line numbers - Added Step 2: Update main.go initialization with line numbers - Added Step 3: Update test_helpers.go with line numbers - Added explanation: Why both DashboardService AND DashboardHandler? ### Updated Phase 10.5.4: Collections Preview Endpoint - Referenced Phase 4.5 (endpoint already implemented earlier) - Clarified needed for web UI AND mobile apps - Noted no additional work needed ### Added Phase 10.6: Implementation Checklist - 30+ checklist items with file paths and verification commands - Organized by layer (Database, Service, Handler, Router, Templates, TypeScript, Tests, Docs) - Added Build & Verification section - Added Timeline Estimate (20-26 hours) - Added Post-Implementation Tasks ## CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md Changes ### Added Clarification Section (at top) - Explained all discrepancies between plan and checklist - Preview endpoint IS in plan (Phase 4.5) - Custom Section Builder IS in plan (Phase 10.5.2 and 10.5.3) - Service method names - Plan is correct - Config struct - Documented with exact line numbers - DashboardService vs DashboardHandler - Explained why both needed ### Updated Service Method Names (Section 3.2) Changed to match plan's actual implementation: - GetDashboardSections (not GetSectionItems) - filterHiddenCollections (not filterHiddenSections) - reorderCollections (not reorderSections) - sortByPriority (new method) - getUserCollectionItems (not getCollectionSections) - getCollectionItemsByQueryType (renamed) ### Enhanced Config Verification (Section 6.4) Added exact line numbers for all 3 files: - internal/router/router.go lines 58-59 - cmd/server/main.go lines 123-124, 172-173 - cmd/server/tests/test_helpers.go lines 419-420, 458-459 ### Updated Preview Endpoint Section (Section 6.3) Added clear explanation of why endpoint is REQUIRED and why NOT client-side. ### Clarified Custom Section Builder (Sections 8.5, 9.4) Both now explicitly state "IS in the plan (Phase 10.5)" ## docs/developer/api/dashboard.md Changes Updated API documentation to match new unified collections architecture: - Terminology: "smart sections" → "system collections" - Field: `type: string` → `is_system: boolean` - Field: `id` → `media_item_id` for books - Request: `hidden_sections` → `hidden_collections` - Request: `section_order` → `collection_order` - Removed: "in-progress" and "unread" smart sections - Added: Update Dashboard Preferences endpoint - Added: Restore System Collection endpoint - Updated: Example responses with new field names and types - Updated: Error responses table ## Impact These changes clarify: 1. Preview endpoint is required for both web UI custom section builder and mobile apps 2. Custom Section Builder IS a major feature in the plan (not missing) 3. Service method names use "collections" terminology consistently 4. Config struct updates are clearly documented with exact line numbers (3 files only) 5. Why both DashboardService AND DashboardHandler are needed in Config All documentation now accurately reflects the finalized Carousel Dashboard architecture.
📚 Bookhoard
A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring universal cross-device sync, beautiful dark themes, and comprehensive media management.
✨ Why Bookhoard?
🔄 Universal Sync: Your reading progress, highlights, and notes sync automatically across all your devices - KOReader, Kobo, web, and mobile.
📱 Multi-Library: Organize your ebooks, comics, and manga with per-library folders and smart collections.
🎨 Beautiful UI: 11 gorgeous dark themes with responsive design that works on any device.
🔒 Secure: JWT authentication, bcrypt password hashing, rate limiting, and no passwords on devices.
🚀 Quick Start
Prerequisites
- Podman (recommended) or Docker
- 5 minutes of your time
Installation
# 1. Clone the repository
git clone https://github.com/yourusername/bookhoard.git
cd bookhoard
# 2. Set up environment
cp .env.example .env
# Generate secure passwords (no special characters):
# JWT_SECRET: openssl rand -hex 32
# DBPASS: openssl rand -hex 16
# Edit .env with your generated values
# 3. Start the server
podman-compose up --build -d # or: docker-compose up --build -d
# 4. Open your browser
open http://localhost:8765
The first user to register automatically becomes an admin.
📖 Key Features
Universal Cross-Platform Sync
- Real-Time Progress: Turn a page on your Kindle, see it on your phone
- Format-Aware: EPUB CFI, page numbers, percentages - all handled correctly
- Offline Queue: Changes sync when you reconnect, priority-processed
- Conflict Resolution: Smart handling when same book read on multiple devices
- Book Matching: Automatic matching using SHA-256, ISBN, UUID
- OPDS Catalog: Wireless book delivery to e-readers over Wi-Fi
- Format Conversion: On-the-fly EPUB→KEPUB for Kobo devices
Media Management
- Smart Search: Partial matching with fuzzy search fallback for typos
- Advanced Filtering: Filter by author, series, genre, language, year, cover images
- Dynamic Sorting: By title, author, date added, published date, page count, series
- Rich Metadata: Title, author, series, publisher, ISBN, language, edition, tags
- 5-Star Ratings: Half-star precision (1-10 scale)
- Notes & Highlights: Color-coded annotations with linked notes
- Usage Analytics: Reading statistics, device usage, popular books
Smart Collections
- Auto-Assign Rules: Automatically add books based on genre, author, series, tags, language, publisher, year
- Device Shelf Mappings: Sync collections to Kobo shelves and KOReader categories
- Test Before Creating: Preview which books match your rules
Library Organization
- Multi-Library Support: Ebooks, Comics, and Manga with type-specific file formats
- Multiple Folders: Add multiple scanning folders per library
- Visibility Control: Admins control which libraries each user can see
- Background Scanning: Auto-scan with per-user frequency settings
- Watch Mode: Real-time file system monitoring for instant updates
Security
- JWT Authentication: Short-lived access tokens (1 hour) with refresh tokens (7 days)
- Strong Passwords: Complexity requirements enforced (8+ chars, uppercase, lowercase, number, special)
- Account Lockout: 5 failed attempts = 15-minute lockout
- Rate Limiting: 10 requests/minute on auth endpoints
- Input Validation: Comprehensive validation on all inputs
- No Passwords on Devices: Web-based device approval with QR codes
📚 Documentation
For Users & Self-Hosters
- docs/user/sync-guide.md - Understanding and using universal sync
- docs/user/devices/kobo-setup.md - Kobo e-reader configuration
- docs/user/devices/koreader-setup.md - KOReader configuration
- docs/user/user-guide.md - General user guide
- docs/user/admin-guide.md - Admin features and configuration
- docs/user/settings-guide.md - Settings and preferences
For Developers
- docs/developer/api/api-reference.md - Complete API documentation
- docs/contributing/DEVELOPMENT.md - Development workflow
🎯 Supported Devices
| Platform | Sync | OPDS | Status |
|---|---|---|---|
| Web Browser | ✅ | ✅ | Full support |
| KOReader | ✅ | ✅ | Kindle, Kobo, PocketBook |
| Kobo Devices | ✅ | ✅ | Clara, Libra, Sage, etc. |
| Mobile Apps | 🚧 | 🚧 | Coming Q2 2026 |
🛠 Tech Stack
- Backend: Go 1.25+ with Echo framework
- Database: PostgreSQL 15+ with pgx v5
- Frontend: HTMX + Tailwind CSS + Templ
- Auth: JWT tokens with bcrypt password hashing
- Container: Podman (Docker compatible)
🧪 Testing
# Run all tests
make test-all
# Run integration tests (with test mode)
make test-integration
# Run Bruno OpenCollection YAML API tests
npm install -g @usebruno/cli
bruno run
📊 Project Status
Version: 1.0
License: GPL-3.0
Status: Production-ready ✅
🤝 Contributing
We welcome contributions! Please see docs/DEVELOPMENT.md for guidelines.
📄 License
GPL-3.0 - See LICENSE file for details.
Built with ❤️ using Go, PostgreSQL, HTMX, and Tailwind CSS