bookhoard/README.md

📚 Bookmann

A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailwind CSS (fully integrated into a single service) featuring multiple beautiful dark themes with Tokyo Night as default.

✨ Features

• 🔒 Multi-User Authentication: Complete user system with registration/login, JWT-based sessions, and bcrypt password hashing
• 👤 User Profile Management: Update profile information, username, email, password, and account deletion
• ⚙️ Scan Settings: Configure scan frequency and auto-scan options per user
• ✅ Server-Side Validation: Comprehensive input validation with detailed error messages
• 🌙 Multiple Themes: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database
• 🎨 Theme Persistence: User theme choices sync between browser and server
• 📖 Reading Progress: User-specific reading progress tracking
• ⭐ Advanced Rating System: 5-star rating with half-star precision, dialog-based input, and zero-rating fallback
• 📁 Multiple Folder Support: Configure multiple ebook folders per user for comprehensive library management
• 🔍 Enhanced Scanner: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction
• 👀 Real-Time Monitoring: File system monitoring for automatic ebook detection and updates
• 📚 Rich Metadata: Automatic extraction of ebook metadata (title, author, description, publisher, series, ISBN, tags) from EPUB files with Calibre-specific support
• 🏛️ Calibre Integration: Full support for Calibre folder structures and metadata (calibre:series, calibre:series_index)
• 📂 Smart Folder Detection: Automatically detects Author/Book, Author/Series/Book, and Calibre naming conventions
• 🔄 Subfolder Scanning: Recursively scans subdirectories with proper folder structure analysis
• 🔧 RESTful API: Clean API endpoints with JWT authentication and proper error handling
• 🐳 Docker Ready: Single-container deployment with PostgreSQL
• 🧪 API Testing: Complete Bruno collection for testing all endpoints
• 📱 Responsive Design: Mobile-first responsive interface using Tailwind CSS
• ⚡ HTMX Integration: Dynamic interactions without JavaScript frameworks
• 🎯 TypeScript Support: Client-side scripting with TypeScript compilation

Quick Start

Prerequisites

• Docker and Docker Compose

Environment Setup

Option 1: Create .env file

# Copy the example environment file
cp .env.example .env

# Edit with your secure values
nano .env  # or your preferred editor

Required Environment Variables:

• JWT_SECRET - Secure random string for JWT authentication
• DBPASS - PostgreSQL database password

Generating Secure Values

Generate JWT Secret:

# Generate 64-byte secure random string
JWT_SECRET=$(openssl rand -base64 64)

Generate Database Password:

# Generate 32-character secure password
DBPASS=$(openssl rand -base64 32 | tr -d '=' '/+' | cut -c1-32)

Add to .env:

echo "JWT_SECRET=$JWT_SECRET" >> .env
echo "DBPASS=$DBPASS" >> .env

Running the Application

Option 1: Using .env file

1. Clone the repository
2. Set up environment:

   cp .env.example .env
   # Edit .env with your secure values
   

3. Run the application:

   docker-compose up --build
   

4. Access the application at http://localhost:8765

Option 2: Using docker-compose variables

1. Clone the repository
2. Set environment variables directly:

   export JWT_SECRET="your-secure-jwt-secret-key-here"
   export DBPASS="your-secure-database-password-here"
   

3. Run the application:

   docker-compose up --build
   

4. Access the application at http://localhost:8765

Database

PostgreSQL runs on port 5432 with default credentials:

• Database: ebookdb
• User: postgres
• Password: password

⚠️ Security Note: Change the default password in production environments! Use the DBPASS environment variable to set a secure password.

Development

Development

go mod tidy
go run github.com/sqlc-dev/sqlc/cmd/sqlc@latest generate
go run cmd/server/main.go

The application uses Go HTML templates for server-side rendering with HTMX for dynamic interactions. Templates are located in templates/.

✨ Enhanced Features:

• Authentication: Login/Register forms with multiple theme support at /login and /register
• JWT Management: Secure token storage with localStorage and session persistence
• Theme Switching: 11 beautiful dark themes with dropdown selector and database persistence
• HTMX Integration: Form submissions and dynamic updates without page reloads
• Input Validation: Server-side validation with detailed error messages
• Multiple Themes: Beautiful dark themes with smooth transitions
• Responsive Design: Mobile-first approach with optimized layouts for all screen sizes

Note: The frontend is fully integrated into the Go backend using HTML templates and HTMX.

API Endpoints

Auth (Public)

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user (email or username)
• GET /api/auth/profile - Get user profile (requires JWT)
• PUT /api/auth/profile - Update user profile (first_name, last_name) (requires JWT)
• PUT /api/auth/theme - Update user theme preference (requires JWT)
• PUT /api/user/username - Update username (requires JWT)
• PUT /api/user/email - Update email (requires JWT)
• PUT /api/user/password - Update password (requires JWT)
• DELETE /api/user/account - Delete user account (requires JWT)

Ebook Folders (Protected)

• POST /api/auth/ebook-folders - Add an ebook folder for scanning
• GET /api/auth/ebook-folders - List user's configured ebook folders
• DELETE /api/auth/ebook-folders - Remove an ebook folder

Library Settings (Protected)

• PUT /api/library/scan-settings - Update scan frequency and auto-scan settings
• GET /api/library/scan-settings - Get current scan settings

Ebooks (Protected)

• GET /api/ebooks - List ebooks
• GET /api/ebooks/:id - Get specific ebook
• POST /api/ebooks - Create new ebook
• PUT /api/ebooks/:id - Update ebook
• DELETE /api/ebooks/:id - Delete ebook

Reading Progress (Protected)

• GET /api/ebooks/:id/progress - Get reading progress
• PUT /api/ebooks/:id/progress - Update reading progress

Ratings (Protected)

• GET /api/ebooks/:id/rating - Get user's rating for ebook (returns 0 when no rating exists)
• POST /api/ebooks/:id/rating - Create or update ebook rating (1-10 scale for half-star precision)
• PUT /api/ebooks/:id/rating - Create or update ebook rating (1-10 scale for half-star precision)
• DELETE /api/ebooks/:id/rating - Delete user's rating
• GET /api/ebooks/:id/ratings - Get all ratings for ebook

Scanner (Protected)

• POST /api/scanner/scan - Scan user's configured ebook folders (supports optional folder_paths parameter for testing)
• POST /api/scanner/start - Start real-time monitoring of configured folders
• POST /api/scanner/stop - Stop real-time folder monitoring

⭐ Interactive Rating System

Bookmann features a fully interactive 5-star rating system integrated directly into the dashboard:

Rating Scale

• Backend: 1-10 scale where odd numbers represent half-stars
  • 1,3,5,7,9 = 0.5,1.5,2.5,3.5,4.5 stars (half-star precision)
  • 2,4,6,8,10 = 1,2,3,4,5 stars (full stars)
• Frontend: 1-5 star display with half-star precision
• 0 stars: Automatically shown when no rating exists
• User-specific: Each user has their own ratings per ebook

Dashboard Integration

• Visual Rating Display: 5-star widgets with half-star precision
• Dialog-based Rating: Click stars to open rating dialog with 0.5 increments
• Half-star Precision: Support for ratings like 3.5, 4.0, 4.5 stars
• Real-time Updates: Rating changes reflect immediately without page reload
• Graceful Fallback: Shows empty stars (☆) for unrated books

API Behavior

• GET /api/ebooks/:id/rating: Returns rating 0 (HTTP 200) when no rating exists
• POST/PUT /api/ebooks/:id/rating: Create or update ratings (1-10 for half-star precision)
• DELETE /api/ebooks/:id/rating: Remove user's rating
• pgx v5 Standards: All database operations use modern pgx error handling

Frontend Features

• Dialog Input: Click stars to rate with precise 0.5 increment control
• Visual Half-stars: Different symbols (⭐) for half-star display
• HTMX Integration: Smooth interactions without full page refreshes
• Responsive Design: Mobile-friendly rating controls
• Theme Support: Rating stars adapt to user's selected theme
• Error Handling: Graceful degradation when API calls fail

📁 Enhanced Ebook Scanner

Bookmann includes an intelligent ebook scanner with full Calibre integration and smart folder structure detection.

Setting Up Folders

1. Add Folders: Use POST /api/auth/ebook-folders to add ebook folders to your account
2. Supported Formats: EPUB (full metadata), PDF (basic), MOBI, AZW3, FB2, TXT
3. Calibre Integration: Automatically recognizes Calibre folder structures and metadata

Folder Structure Support

Calibre Structure (Preferred)

• Author Name/Book Title/ - Simple Calibre structure
• Author Name/Series Name/Book Title/ - Series-based structure
• Author Name/Series Name, Book #1 - Book Title/ - Full Calibre naming with series numbers

Alternative Structures

• Flat folder structures (all ebooks in root folder)
• Custom subfolder organization
• Mixed structures (Calibre + custom folders)

Example Folder Structures

Calibre Standard

Books/
├── Brandon Sanderson/
│   ├── Mistborn/
│   │   ├── The Final Empire.epub
│   │   └── The Well of Ascension.epub
│   └── The Stormlight Archive/
│       ├── The Way of Kings.epub
│       └── Words of Radiance.epub
└── Patrick Rothfuss/
    └── The Kingkiller Chronicle/
        ├── The Name of the Wind.epub
        └── The Wise Man's Fear.epub

Calibre with Series Numbers

Books/
├── Brandon Sanderson/
│   ├── Mistborn Trilogy, Book #1 - The Final Empire/
│   │   └── The Final Empire.epub
│   └── Mistborn Trilogy, Book #2 - The Well of Ascension/
│       └── The Well of Ascension.epub

Metadata Extraction

File-based Metadata

• EPUB: Title, Author, Description, Publisher, Series, Series Number, ISBN, Tags, Contributors, Publish Date
• PDF: Basic filename extraction (can be enhanced with PDF library)
• Other formats: Filename as title

Folder-based Metadata (Fallback)

• Extracts author from folder name
• Extracts series information from folder structure
• Detects series numbers from folder names
• Handles underscore-to-space conversion

Enhanced Features

• Priority: File metadata > Folder structure metadata > Filename fallback
• Subfolder watching: Automatically watches new subdirectories
• Real-time updates: Processes new/modified files immediately
• Calibre-specific support: Reads calibre:series and calibre:series_index metadata

PDF & Other Formats

• Basic filename extraction
• Folder structure metadata fallback

Scanner Operations

• Manual Scan: POST /api/scanner/scan - Immediately scan all configured folders
• Start Monitoring: POST /api/scanner/start - Begin real-time monitoring for changes
• Stop Monitoring: POST /api/scanner/stop - Stop monitoring (folders remain configured)

Advanced Features

• Subfolder Scanning: Recursively scans all subdirectories
• Smart Error Handling: Properly handles file system errors and database issues
• Metadata Priority: File metadata → Folder structure → Filename fallback
• Real-Time Detection: Automatic discovery of new and modified ebooks
• Duplicate Prevention: Updates existing entries instead of creating duplicates
• Dynamic Watching: Automatically watches new subdirectories as they're created

API Testing

Use the included Bruno collection in the bruno/ directory for testing the API:

1. Install Bruno
2. Import the bruno/ folder as a collection
3. Select the "localhost" environment
4. Run the application and test the endpoints

Project Structure

.
├── cmd/server/              # Application entry point
│   ├── main.go             # Main server application
│   └── static/             # Static web assets (CSS, JS, images)
├── internal/
│   ├── config/              # Configuration management
│   ├── database/            # Database connection and queries
│   ├── handlers/            # HTTP handlers (auth + ebooks)
│   └── services/            # Business logic services (ebook scanner)
├── database/schema/          # Database schema definitions
├── templates/               # Go HTML templates with HTMX
├── bruno/                   # Bruno API testing collection
├── Dockerfile               # Docker build configuration
├── docker-compose.yml       # Docker Compose setup
├── go.mod                   # Go module definition
├── go.sum                   # Go module checksums
├── internal/database/sqlc.yaml  # SQL code generation config
└── README.md

🎨 Recent Enhancements

Major Scanner Improvements

• Calibre Integration: Full support for Calibre folder structures and metadata fields
• Smart Folder Detection: Automatically recognizes Author/Book, Author/Series/Book patterns
• Enhanced Metadata Extraction: EPUB parsing with Calibre-specific support (calibre:series, calibre:series_index, ISBN, tags)
• Subfolder Scanning: Recursive directory scanning with automatic new folder watching
• Robust Error Handling: Proper pgx.ErrNoRows handling and comprehensive error recovery
• Folder-based Metadata: Fallback metadata extraction from folder structures when file metadata is incomplete
• Multi-format Support: EPUB (full), PDF (basic), MOBI, AZW3, FB2, TXT file formats

Backend Improvements

• Server-Side Rendering: Replaced static frontend with Go HTML templates
• Theme System: Database-backed user theme preferences with 11 beautiful dark themes
• HTMX Integration: Dynamic interactions using HTMX for modern UX
• Enhanced Security: JWT authentication with proper error handling
• User Profile Management: Full CRUD operations for user profiles, usernames, emails, passwords, and account deletion
• Multiple Folder Support: Users can configure multiple ebook directories with per-user folder management
• Real-Time Monitoring: File system watching for automatic ebook updates with dynamic subfolder detection
• Scan Settings: User-configurable scan frequency and auto-scan options
• Advanced Rating System: 5-star display with half-star precision, dialog-based rating input, 10-point backend scale, and full CRUD operations

Frontend Redesign

• Beautiful Homepage: Hero section with features showcase and modern design
• Multiple Themes: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with CSS variables
• HTMX Forms: Real-time form submissions and updates without JavaScript frameworks
• Theme Switcher: Dropdown selector that saves preferences to database
• Responsive Design: Tailwind CSS for mobile-first responsive layouts
• Smooth Animations: CSS transitions and scroll effects

Technical Updates

• Go Templates: Server-side rendering with template inheritance
• Tailwind CSS: Local build system with production optimization and minification
• TypeScript Support: Client-side scripting with TypeScript compilation
• Database Schema: Enhanced with user profiles, user_ebook_folders, ebook_ratings tables
• API Expansion: Comprehensive endpoints for user management, folder operations, scanner controls, and ratings
• Advanced Metadata: Rich ebook information extraction with fallback strategies
• File System Monitoring: Real-time folder watching with automatic new directory detection
• Error Recovery: Robust database error handling with proper pgx integration
• Local Build System: Self-contained CSS/JS assets without CDN dependencies

License

GPL-3.0