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
• ✅ 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
• 📁 Multiple Folder Support: Configure multiple ebook folders per user for comprehensive library management
• 🔍 Smart Scanner: Automatic ebook discovery with EPUB metadata extraction (title, author, description, publisher, etc.)
• 👀 Real-Time Monitoring: File system monitoring for automatic ebook detection and updates
• 📚 Rich Metadata: Automatic extraction of ebook metadata from EPUB files
• 🔧 RESTful API: Clean API endpoints with JWT authentication
• 🐳 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

Backend

cd backend
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 backend/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: 7 popular 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/theme - Update user theme preference (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/:folderPath - Remove an ebook folder

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 - Manually scan configured folders for ebooks
• POST /api/scanner/start - Start real-time monitoring of configured folders
• POST /api/scanner/stop - Stop real-time folder monitoring

📁 Ebook Scanner

Bookmann includes an intelligent ebook scanner that can automatically discover and catalog ebooks from your configured folders.

Setting Up Folders

1. Add Folders: Use the API or Bruno to add ebook folders to your account
2. Supported Formats: EPUB, PDF, MOBI, AZW3, FB2, TXT
3. Metadata Extraction: EPUB files automatically get rich metadata (title, author, description, publisher, etc.)

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)

Real-Time Features

• Auto-Discovery: New ebooks added to folders are automatically detected
• Metadata Updates: Modified files get updated metadata
• Duplicate Prevention: Existing ebooks are updated, not duplicated
• Multi-Folder Support: Monitor multiple directories simultaneously

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

.
├── backend/
│   ├── cmd/server/          # Application entry point
│   ├── internal/
│   │   ├── config/          # Configuration management
│   │   ├── database/        # Database connection and queries
│   │   ├── handlers/        # HTTP handlers (auth + ebooks)
│   │   └── services/        # Business logic services (ebook scanner)
│   ├── migrations/          # Database migrations
│   ├── templates/           # Go HTML templates with HTMX
│   └── sqlc.yaml            # sqlc configuration
├── bruno/                   # Bruno API testing collection
├── docker-compose.yml
└── README.md

🎨 Recent Enhancements

Backend Improvements

• Server-Side Rendering: Replaced static frontend with Go HTML templates
• Theme System: Database-backed user theme preferences with 7 popular dark themes
• HTMX Integration: Dynamic interactions using HTMX for modern UX
• Enhanced Security: JWT authentication with theme persistence
• Multiple Folder Support: Users can configure multiple ebook directories
• Smart Ebook Scanner: Automatic discovery and metadata extraction from EPUB files
• Real-Time Monitoring: File system watching for automatic ebook updates

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: Utility-first CSS framework via CDN
• TypeScript Support: Client-side scripting with TypeScript compilation
• Database Schema: Added user_ebook_folders table for multiple folder support
• API Expansion: New endpoints for folder management and scanner operations
• Metadata Extraction: EPUB parsing for rich ebook information
• File System Monitoring: Real-time folder watching with fsnotify

License

GPL-3.0