docs: update README for complete library system
- Document new multi-library architecture (ebooks, comics, manga) - Detail per-library folder management and visibility controls - Include comprehensive API documentation with Bruno examples - Add pgx v5 compliance and security best practices - Update deployment and development instructions - Document JWT authentication and role-based access control - Include future roadmap for audiobooks, video, podcasts, etc. Provides complete overview of transformed system for users and developers
This commit is contained in:
@@ -1,509 +1,349 @@
|
||||
# 📚 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.
|
||||
A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring multiple library support, beautiful dark themes, and comprehensive media management.
|
||||
|
||||
## ✨ 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
|
||||
### 🏗 Multi-Library System
|
||||
- **Multiple Media Types**: Support for Ebooks, Comics, and Manga with modular architecture
|
||||
- **Per-Library Folders**: Each library can have multiple scanning folders for flexible organization
|
||||
- **Library Visibility Control**: Admins can control which libraries are visible to each user
|
||||
- **Type-Specific File Extensions**:
|
||||
- **Ebooks**: `.epub`, `.pdf`, `.mobi`, `.azw`, `.azw3`, `.txt`, `.rtf`, `.doc`, `.docx`, `.lit`, `.fb2`, `.pdb`
|
||||
- **Comics**: `.cbz`, `.cbr`, `.cb7`, `.cbt`, `.pdf`
|
||||
- **Manga**: `.cbz`, `.cbr`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`
|
||||
- **Easy Extension**: Designed to add new media types in the future
|
||||
|
||||
## Quick Start
|
||||
### 🔒 Authentication & Security
|
||||
- **Multi-User Support**: Complete user registration and authentication system
|
||||
- **JWT-Based Sessions**: Secure token-based authentication with localStorage persistence
|
||||
- **Role-Based Access**: Admin and user roles with granular permission control
|
||||
- **Password Security**: bcrypt hashing with secure password requirements
|
||||
|
||||
### 🎨 Beautiful UI
|
||||
- **11 Dark Themes**: Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, Catppuccin variants
|
||||
- **Theme Persistence**: User theme preferences saved to database
|
||||
- **Mobile-First Design**: Fully responsive interface for all devices
|
||||
- **HTMX Integration**: Dynamic interactions without page reloads
|
||||
|
||||
### 📱 Media Management
|
||||
- **Universal Media Support**: Single system for all media types with unified interface
|
||||
- **Rich Metadata**: Automatic extraction of title, author, series, publisher, ISBN, tags
|
||||
- **Advanced Rating**: 5-star system with half-star precision (1-10 scale)
|
||||
- **Reading Progress**: User-specific progress tracking with current page and total pages
|
||||
- **Library Statistics**: Media count and usage statistics per library
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- PostgreSQL database (handled by Docker)
|
||||
|
||||
### Environment Setup
|
||||
|
||||
**Option 1: Create .env file**
|
||||
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:**
|
||||
2. **Edit .env** with your secure values:
|
||||
```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
|
||||
JWT_SECRET="your-secure-jwt-secret-key-here"
|
||||
DBPASS="your-secure-database-password-here"
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
```bash
|
||||
# Option 1: Using .env file
|
||||
docker-compose up --build
|
||||
|
||||
**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: Direct environment variables
|
||||
export JWT_SECRET="your-secure-jwt-secret-key-here"
|
||||
export DBPASS="your-secure-database-password-here"
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
**Option 2: Using psql**
|
||||
```bash
|
||||
# Connect to the running database container
|
||||
Access the application at: **http://localhost:8765**
|
||||
|
||||
## 👤 User Management
|
||||
|
||||
### Role System
|
||||
- **Admin Users**: Can create/manage libraries, add/delete media items, manage users
|
||||
- **Regular Users**: Can view permitted libraries, rate items, track reading progress
|
||||
|
||||
### First Admin Setup
|
||||
The first user who registers automatically becomes an admin. For additional admins:
|
||||
|
||||
```sql
|
||||
-- Connect to database
|
||||
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
|
||||
-- Promote user to admin
|
||||
UPDATE users SET role = 'admin' WHERE email = 'user@example.com';
|
||||
```
|
||||
|
||||
**Option 2: Using psql**
|
||||
## 🏛 Library Management
|
||||
|
||||
### Creating Libraries
|
||||
1. **Admin Access**: Only administrators can create libraries
|
||||
2. **Library Types**: Choose from Ebooks, Comics, or Manga
|
||||
3. **Multi-Folder Support**: Add multiple scanning folders per library
|
||||
4. **Folder Organization**: Organize your media collection across multiple paths
|
||||
|
||||
### Library Visibility Control
|
||||
- **Admin Dashboard**: Complete interface for managing library access
|
||||
- **User-Specific Control**: Admins can show/hide libraries per user
|
||||
- **Personal Preferences**: Admins can also hide libraries from their own view
|
||||
- **Simple Toggles**: Checkbox-based interface for easy management
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### Library Management (Admin Only)
|
||||
```bash
|
||||
# Connect to the running database container
|
||||
docker exec -it bookmann-db-1 psql -U postgres -d bookmann
|
||||
# Create new library
|
||||
POST /api/libraries
|
||||
{
|
||||
"name": "My Comic Collection",
|
||||
"description": "Digital comics and graphic novels",
|
||||
"type": "comics"
|
||||
}
|
||||
|
||||
# Update user role
|
||||
UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
|
||||
# List all libraries
|
||||
GET /api/libraries
|
||||
|
||||
# Exit psql
|
||||
\q
|
||||
# Add folder to library
|
||||
POST /api/libraries/{library_id}/folders
|
||||
{
|
||||
"folder_path": "/path/to/comics"
|
||||
}
|
||||
|
||||
# Set library visibility for user
|
||||
POST /api/libraries/visibility
|
||||
{
|
||||
"library_id": "library-uuid",
|
||||
"is_visible": true
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
#### User Access
|
||||
```bash
|
||||
# Get user's visible libraries
|
||||
GET /api/libraries/visible
|
||||
|
||||
**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
|
||||
# Browse media in library
|
||||
GET /api/media-items?library_id={library_id}&limit=20&offset=0
|
||||
```
|
||||
|
||||
## 📖 Media Support
|
||||
|
||||
### Ebooks
|
||||
- **Formats**: EPUB (full metadata), PDF, MOBI, AZW, TXT, DOC, FB2
|
||||
- **Metadata**: Automatic extraction from EPUB files with Calibre support
|
||||
- **Reading**: Built-in web reader for EPUB files
|
||||
|
||||
### Comics
|
||||
- **Formats**: CBZ, CBR, CB7, CBT, PDF
|
||||
- **Structure**: Archive-based organization with chapter support
|
||||
- **Viewing**: Image extraction and web-based comic reader
|
||||
|
||||
### Manga
|
||||
- **Formats**: CBZ, CBR (archives), PNG, JPG (image folders)
|
||||
- **Structure**: Archive support with folder-based image organization
|
||||
- **Viewing**: Chapter-by-chapter viewing with page navigation
|
||||
|
||||
## 🎨 Development
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# Backend development
|
||||
go mod tidy
|
||||
go run cmd/server/main.go
|
||||
|
||||
# Frontend development
|
||||
npm run dev
|
||||
# Templates automatically recompile on changes
|
||||
```
|
||||
|
||||
### Environment
|
||||
- **Backend**: Go 1.25+ with pgx v5 for database operations
|
||||
- **Frontend**: Tailwind CSS with HTMX for dynamic interactions
|
||||
- **Database**: PostgreSQL 15+ with pgx v5 driver
|
||||
- **Authentication**: JWT tokens with bcrypt password hashing
|
||||
|
||||
## 🐳 Deployment
|
||||
|
||||
### Docker Configuration
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
bookmann:
|
||||
build: .
|
||||
ports:
|
||||
- "8765:8765"
|
||||
environment:
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
- DBHOST=db
|
||||
depends_on:
|
||||
- db
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
- **Multi-Library Architecture**: Libraries, library types, folders, visibility tables
|
||||
- **Backward Compatibility**: Views maintain existing API contracts
|
||||
- **Type Safety**: pgx v5 with proper error handling
|
||||
- **Migration Ready**: Schema designed for easy future extensions
|
||||
|
||||
## 🧪 API Documentation
|
||||
|
||||
### Bruno Testing Collection
|
||||
Complete API testing collection in `bruno/` directory:
|
||||
|
||||
```
|
||||
bruno/
|
||||
├── user/ # Authentication & profile endpoints
|
||||
├── admin/ # Admin-only operations
|
||||
├── library/ # Library management
|
||||
├── media-items/ # Media content browsing
|
||||
└── collection.bru # Main dashboard
|
||||
```
|
||||
|
||||
### Authentication Flow
|
||||
1. **Register**: `POST /api/auth/register` → JWT token
|
||||
2. **Login**: `POST /api/auth/login` → JWT token
|
||||
3. **Protected Routes**: Use `Authorization: Bearer {token}` header
|
||||
|
||||
### Error Handling
|
||||
- **400**: Bad request (validation errors)
|
||||
- **401**: Unauthorized (invalid/missing token)
|
||||
- **403**: Forbidden (insufficient permissions)
|
||||
- **404**: Resource not found
|
||||
- **500**: Internal server error
|
||||
|
||||
## 🛡 Security Features
|
||||
|
||||
### Authentication
|
||||
- **JWT Tokens**: Secure, expiring tokens with localStorage persistence
|
||||
- **Password Hashing**: bcrypt with cost factor 12
|
||||
- **Input Validation**: Comprehensive server-side validation
|
||||
- **CSRF Protection**: Built-in with HTMX
|
||||
|
||||
### Authorization
|
||||
- **Role-Based Access**: Admin vs user permissions
|
||||
- **Library Visibility**: Per-user library access control
|
||||
- **Admin Middleware**: Protected routes for admin operations
|
||||
- **Content Security**: XSS protection and secure headers
|
||||
|
||||
### Database Security
|
||||
- **Parameterized Queries**: SQL injection prevention
|
||||
- **pgx v5**: Modern database driver with connection pooling
|
||||
- **Environment Variables**: Secure secret management
|
||||
- **Row-Level Security**: User data isolation
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Required
|
||||
JWT_SECRET= # JWT signing secret (64-byte random string)
|
||||
DBHOST=db # PostgreSQL database host
|
||||
|
||||
# Optional
|
||||
SERVER_PORT=8765 # Application port
|
||||
NODE_ENV=development # Environment mode
|
||||
```
|
||||
|
||||
### Database Configuration
|
||||
```sql
|
||||
-- Library types are automatically seeded
|
||||
INSERT INTO library_types (name, description, allowed_extensions) VALUES
|
||||
('ebooks', 'Ebook files including EPUB, PDF, MOBI, etc.',
|
||||
ARRAY['.epub', '.pdf', '.mobi', '.azw', '.azw3', '.txt', '.rtf', '.doc', '.docx', '.lit', '.fb2', '.pdb']),
|
||||
('comics', 'Comic book archives and image formats',
|
||||
ARRAY['.cbz', '.cbr', '.cb7', '.cbt', '.pdf']),
|
||||
('manga', 'Manga files including archives and image folders',
|
||||
ARRAY['.cbz', '.cbr', '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp']);
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### API Testing
|
||||
```bash
|
||||
# Install Bruno
|
||||
npm install -g @usebruno/cli
|
||||
|
||||
# Run tests
|
||||
bruno run
|
||||
```
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## 📊 Architecture
|
||||
|
||||
### Backend
|
||||
```
|
||||
cmd/server/main.go # Application entry point
|
||||
├── internal/
|
||||
│ ├── config/ # Configuration management
|
||||
│ ├── database/ # Database operations (SQLC generated)
|
||||
│ │ ├── queries/ # SQL queries
|
||||
│ │ └── models.go # Generated models
|
||||
│ ├── handlers/ # HTTP handlers
|
||||
│ │ ├── auth.go # Authentication & users
|
||||
│ │ ├── library.go # Library management
|
||||
│ │ └── ebook.go # Media operations
|
||||
│ └── services/ # Business logic
|
||||
│ └── library_service.go # Library service
|
||||
templates/ # HTML templates with HTMX
|
||||
```
|
||||
|
||||
### 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
|
||||
```sql
|
||||
libraries # Library definitions
|
||||
library_types # Media type definitions (ebooks, comics, manga)
|
||||
library_folders # Folders per library
|
||||
library_visibility # User library access control
|
||||
media_items # All media content (replaces ebooks table)
|
||||
media_ratings # User ratings for media items
|
||||
reading_progress # User reading progress
|
||||
users # User accounts and profiles
|
||||
```
|
||||
|
||||
The application uses Go HTML templates for server-side rendering with HTMX for dynamic interactions. Templates are located in `templates/`.
|
||||
## 🎯 Future Roadmap
|
||||
|
||||
**✨ 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)
|
||||
### Media Type Extensions
|
||||
- **Audiobooks**: Audio file support with chapter tracking
|
||||
- **Podcasts**: RSS feed integration and automatic downloading
|
||||
- **Video**: Movie/TV series management with metadata
|
||||
- **Music**: Album and track management with artwork
|
||||
|
||||
### Advanced Features
|
||||
- **Mobile App**: React Native mobile application
|
||||
- **API v2**: GraphQL API for efficient data fetching
|
||||
- **Webhooks**: External service integrations
|
||||
- **Analytics**: Usage statistics and reporting
|
||||
- **Backup/Restore**: Library backup and migration tools
|
||||
|
||||
- **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
|
||||
## 📝 Contributing
|
||||
|
||||
## API Testing
|
||||
### Development Guidelines
|
||||
- Follow Go best practices and effective Go
|
||||
- Use pgx v5 for all database operations
|
||||
- Implement proper error handling with pgx.ErrNoRows
|
||||
- Write comprehensive tests for new features
|
||||
- Update documentation for API changes
|
||||
|
||||
Use the included Bruno collection in the `bruno/` directory for testing the API:
|
||||
### Code Style
|
||||
- Follow existing code formatting
|
||||
- Use meaningful variable and function names
|
||||
- Add comments for complex business logic
|
||||
- Ensure type safety with proper error handling
|
||||
|
||||
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
|
||||
## 📄 License
|
||||
|
||||
## Project Structure
|
||||
GPL-3.0 - See [LICENSE](LICENSE) file for details.
|
||||
|
||||
```
|
||||
.
|
||||
├── 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
|
||||
**Built with ❤️ using Go, PostgreSQL, HTMX, and Tailwind CSS**
|
||||
Reference in New Issue
Block a user