📚 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
• ⭐ User Ratings: Rate and review ebooks with personalized rating system
• 📁 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

Running the Application

1. Clone the repository
2. Run the application:

docker-compose up --build

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

Database

PostgreSQL runs on port 5432 with default credentials:

• Database: ebookdb
• User: postgres
• Password: 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
• POST /api/ebooks/:id/rating - Create or update ebook rating
• PUT /api/ebooks/:id/rating - Create or update ebook rating
• 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

📁 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
• Rating System: User-specific ebook ratings with 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