john-okeefe
08e80ae84b
- Move migrations/ to database/schema/ for clarity on database schema definitions - Move sqlc.yaml to internal/database/ to group with database code - Move static/ to cmd/server/static/ to co-locate with server - Update all configuration files and documentation - Follow Go project conventions for better organization
283 lines
13 KiB
Markdown
283 lines
13 KiB
Markdown
# 📚 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://www.usebruno.com/)
|
|
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**: Utility-first CSS framework via CDN
|
|
- **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
|
|
|
|
## License
|
|
|
|
GPL-3.0 |