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
- **👑 Admin-Based Control**: Role-based access control with admin privileges for folder and ebook management
- **👤 User Profile Management**: Update profile information, username, email, password, and account deletion
- **⚙️ Scan Settings**: Configure scan frequency and auto-scan options per user (admin only)
- **✅ 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
- **📁 Folder Management**: Configure and manage ebook folders (admin only)
- **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction (admin only)
- **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates (admin only)
- **📚 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
- **🛡️ Role-Based Security**: Admin users can manage folders and ebook metadata; regular users can view, rate, and track reading progress
- **📋 Shared Library**: All users can view the complete ebook collection, with admin tracking of who added each book
- **🐳 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**
```bash
# 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

### API Testing

The `bruno/` directory contains a comprehensive API testing collection organized into logical subfolders for testing all endpoints:

#### **Collection Structure**
```
bruno/user/
├── auth/                    # Authentication requests
│   ├── Login User.bru      # POST /api/auth/login
│   └── Register User.bru   # POST /api/auth/register (with restrictions)
├── admin/                   # Admin-only management
│   ├── List Users.bru         # GET /api/auth/users (admin only)
│   ├── Delete Account.bru       # DELETE /api/auth/account (admin override)
│   └── Register Admin User.bru # POST /api/auth/register (admin creation)
└── profile/                  # Profile management
    ├── Get Profile.bru         # GET /api/auth/profile
    ├── Update Profile.bru       # PUT /api/auth/profile
    ├── Update Email.bru         # PUT /api/auth/email
    ├── Update Password.bru       # PUT /api/auth/password
    ├── Update Theme.bru         # PUT /api/auth/theme
    └── Update Username.bru       # PUT /api/auth/username
```

#### **Usage**
1. Install Bruno: https://www.usebruno.com/
2. Import Collection: Open Bruno and import the `bruno/` folder
3. Select Environment: Choose the "Bookmann" environment
4. Authentication Flow: Register → Login → Use Bearer token for protected routes

### Generating Secure Values

**Generate JWT Secret:**
```bash
# Generate 64-byte secure random string
JWT_SECRET=$(openssl rand -base64 64)
```

**Generate Database Password:**
```bash
# Generate 32-character secure password
DBPASS=$(openssl rand -base64 32 | tr -d '=' '/+' | cut -c1-32)
```

**Add to .env:**
```bash
echo "JWT_SECRET=$JWT_SECRET" >> .env
echo "DBPASS=$DBPASS" >> .env
```

### Running the Application

**Option 1: Using .env file**
1. Clone repository
2. Set up environment:
    ```bash
    cp .env.example .env
    # Edit .env with your secure values
    ```
3. Run the application:
    ```bash
    docker-compose up --build
    ```
4. Access the application at http://localhost:8765

### Admin Setup

The first user who registers automatically becomes an admin. For subsequent users, you can manually set admin privileges:

**Option 1: Direct Database Update**
```sql
-- Connect to database and update user role
UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
```

**Option 2: Using psql**
```bash
# Connect to the running database container
docker exec -it bookmann_db psql -U postgres -d bookmann

# Update user role
UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';

# Exit psql
\q
```

**Option 2: Using psql**
```bash
# Connect to the running database container
docker exec -it bookmann-db-1 psql -U postgres -d bookmann

# Update user role
UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';

# Exit psql
\q
```

**Role Permissions:**
- **Admin Users**: Can add/edit/delete folders, scan ebooks, modify/delete any ebook metadata
- **Regular Users**: Can view all ebooks, rate books, track reading progress, manage their profile
- **Shared Library**: All users see the same ebook collection, but only admins can modify it
- **First User Protection**: The very first user to register automatically becomes admin
- **Last User Protection**: The system prevents deletion of the last remaining user account

**Option 2: Using docker-compose variables**
1. Clone the repository
2. Set environment variables directly:
   ```bash
   export JWT_SECRET="your-secure-jwt-secret-key-here"
   export DBPASS="your-secure-database-password-here"
   ```
3. Run the application:
   ```bash
   docker-compose up --build
   ```
4. Access the application at http://localhost:8765

### Database

PostgreSQL runs on port 5432 with default credentials:
- Database: bookmann
- 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

```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

### Bruno API Testing Collection

The `bruno/` directory contains a comprehensive API testing collection organized into logical subfolders:

#### **Collection Structure**
```
bruno/user/
├── auth/                    # Authentication requests
│   ├── Login User.bru      # POST /api/auth/login
│   └── Register User.bru   # POST /api/auth/register (with restrictions)
├── admin/                   # Admin-only management
│   ├── List Users.bru         # GET /api/auth/users (admin only)
│   ├── Delete Account.bru       # DELETE /api/auth/account (admin override)
│   └── Register Admin User.bru # POST /api/auth/register (admin creation)
└── profile/                  # Profile management
    ├── Get Profile.bru         # GET /api/auth/profile
    ├── Update Profile.bru       # PUT /api/auth/profile
    ├── Update Email.bru         # PUT /api/auth/email
    ├── Update Password.bru       # PUT /api/auth/password
    ├── Update Theme.bru         # PUT /api/auth/theme
    └── Update Username.bru       # PUT /api/auth/username
```

#### **Setup Instructions**
1. **Install Bruno**: https://www.usebruno.com/
2. **Import Collection**: Open Bruno and import the `bruno/` folder
3. **Select Environment**: Choose the "Bookmann" environment
4. **Start Application**: `docker-compose up --build`
5. **Authentication Flow**: Register → Login → Use Bearer token for protected routes

#### **Security Features**
- **Role-Based Registration**: Admin creation restrictions documented and tested
- **Admin-Only Endpoints**: Proper access control for sensitive operations
- **Token Management**: Automatic token persistence for workflow testing
- **Error Handling**: Comprehensive status codes and error messages

#### **Available Tests**
- **User Registration**: Regular and admin account creation
- **Authentication**: Login with email/username flexibility
- **Profile Management**: Complete CRUD operations for user profiles
- **Admin Operations**: User listing, account management with override
- **Ebook Operations**: Full CRUD with ratings and progress tracking

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

## API Endpoints

### Authentication (Public & Protected)
- `POST /api/auth/register` - Register new user (role field: "user" or "admin")
  - **Auto-Admin**: First user automatically gets admin role
  - **Role Restrictions**: Role-based creation restrictions apply:
    - First user always gets admin role regardless of request
    - If any admin exists, only authenticated admins can create new admin accounts
    - Regular users can always create user accounts
    - Unauthenticated users can only create first admin, not subsequent admins
- `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/auth/username` - Update username (requires JWT)
- `PUT /api/auth/email` - Update email (requires JWT)
- `PUT /api/auth/password` - Update password (requires JWT)
- `DELETE /api/auth/account` - Delete user account (requires JWT)
  - **Self-Deletion**: Users can delete their own accounts
  - **Admin Override**: Admins can delete any user account via `?user_id={uuid}` parameter
  - **Protection**: Cannot delete the last admin account

### Admin Management (Admin Only)
- `GET /api/auth/users` - List all users with complete info (admin only)
- `DELETE /api/auth/account` - Delete own account or admin deletes other accounts with `user_id` parameter
- `POST /api/auth/ebook-folders` - Add an ebook folder for scanning
- `GET /api/auth/ebook-folders` - List configured ebook folders
- `DELETE /api/auth/ebook-folders` - Remove an ebook folder

### Library Settings (Admin Only)
- `PUT /api/library/scan-settings` - Update scan frequency and auto-scan settings
- `GET /api/library/scan-settings` - Get current scan settings

### Ebooks (Mixed Access)
- `GET /api/ebooks` - List ebooks (all authenticated users)
- `GET /api/ebooks/:id` - Get specific ebook (all authenticated users)
- `POST /api/ebooks` - Create new ebook (admin only, tracks admin who added it)
- `PUT /api/ebooks/:id` - Update ebook (admin only)
- `DELETE /api/ebooks/:id` - Delete ebook (admin only)

### 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 (Admin Only)
- `POST /api/scanner/scan` - Scan 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 (admin only)
2. **Supported Formats**: EPUB (full metadata), PDF (basic), MOBI, AZW3, FB2, TXT
3. **Calibre Integration**: Automatically recognizes Calibre folder structures and metadata
4. **Admin Privileges**: Only administrators can configure folders and initiate scans

### 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

### 🔒 Admin-Based Control System
- **Role-Based Access**: Implemented complete role system with 'admin' and 'user' roles
- **Admin Middleware**: Created authorization middleware for protected operations
- **Folder Management**: Only admins can add/edit/delete ebook folders and configure scanner
- **Ebook CRUD**: Only admins can create, update, or delete ebook metadata
- **Scanner Control**: Only admins can initiate scans and control file system monitoring
- **Shared Library**: All users can view ebooks, but only admins can modify the library
- **Admin Tracking**: Ebooks track which admin added them via `added_by_admin_id` field
- **Frontend Protection**: Admin controls only visible to users with admin role

### 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