From 152ed2720052b8d4eefe53a99890a6fbfc512c5f Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Fri, 23 Jan 2026 09:04:59 -0500 Subject: [PATCH] docs: update README with multiple folder support and scanner functionality - Add multiple folder support and smart scanner to features list - Document new API endpoints for folder management and scanner operations - Update project structure to include services directory - Add comprehensive ebook scanner section with usage instructions - Update recent enhancements with latest backend improvements - Include real-time monitoring and metadata extraction details --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7288029..2179f23 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,10 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw - **πŸŒ™ 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 @@ -72,6 +76,11 @@ The application uses Go HTML templates for server-side rendering with HTMX for d - `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 @@ -90,6 +99,34 @@ The application uses Go HTML templates for server-side rendering with HTMX for d - `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: @@ -108,7 +145,8 @@ Use the included Bruno collection in the `bruno/` directory for testing the API: β”‚ β”œβ”€β”€ internal/ β”‚ β”‚ β”œβ”€β”€ config/ # Configuration management β”‚ β”‚ β”œβ”€β”€ database/ # Database connection and queries -β”‚ β”‚ └── handlers/ # HTTP handlers (auth + ebooks) +β”‚ β”‚ β”œβ”€β”€ handlers/ # HTTP handlers (auth + ebooks) +β”‚ β”‚ └── services/ # Business logic services (ebook scanner) β”‚ β”œβ”€β”€ migrations/ # Database migrations β”‚ β”œβ”€β”€ templates/ # Go HTML templates with HTMX β”‚ └── sqlc.yaml # sqlc configuration @@ -124,6 +162,9 @@ Use the included Bruno collection in the `bruno/` directory for testing the API: - **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 @@ -137,8 +178,10 @@ Use the included Bruno collection in the `bruno/` directory for testing the API: - **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 theme column to users table -- **API Expansion**: New theme update endpoint +- **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