Update documentation to reflect interactive rating system and API changes

- Update README.md with interactive rating system details
- Document zero-rating behavior in GET /api/ebooks/:id/rating
- Add comprehensive rating system documentation section
- Update Bruno collection files to reflect new API behavior
- Enhance API testing documentation with rating 0 fallback

README.md

@@ -11,7 +11,7 @@ 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
-- **⭐ User Ratings**: Rate and review ebooks with personalized rating system
+- **⭐ Interactive Rating System**: 5-star rating system with interactive dashboard controls and zero-rating fallback
 - **📁 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
@@ -161,9 +161,9 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `PUT /api/ebooks/:id/progress` - Update reading progress
 
 ### Ratings (Protected)
-- `GET /api/ebooks/:id/rating` - Get user's rating for ebook
+- `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
+- `POST /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars)
-- `PUT /api/ebooks/:id/rating` - Create or update ebook rating
+- `PUT /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars)
 - `DELETE /api/ebooks/:id/rating` - Delete user's rating
 - `GET /api/ebooks/:id/ratings` - Get all ratings for ebook
 
@@ -172,6 +172,33 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `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
+- **1-5 stars**: Standard rating scale for ebooks
+- **0 stars**: Automatically shown when no rating exists
+- **User-specific**: Each user has their own ratings per ebook
+
+### Dashboard Integration
+- **Visual Rating Display**: Interactive star widgets for each ebook
+- **Click-to-Rate**: Simply click on stars to set/update ratings
+- **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-5)
+- **DELETE /api/ebooks/:id/rating**: Remove user's rating
+- **pgx v5 Standards**: All database operations use modern pgx error handling
+
+### Frontend Features
+- **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.
@@ -312,7 +339,7 @@ Use the included Bruno collection in the `bruno/` directory for testing the API:
 - **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
+- **Interactive Rating System**: 5-star dashboard controls with click-to-rate functionality, zero-rating fallback, and full CRUD operations
 
 ### Frontend Redesign
 - **Beautiful Homepage**: Hero section with features showcase and modern design

bruno/README.md

@@ -29,7 +29,7 @@ This directory contains Bruno collection for testing the Bookmann API with compr
 - **Update Reading Progress**: PUT /api/ebooks/:id/progress - Update progress
 
 ### Ratings (Protected - JWT Required)
-- **Get Ebook Rating**: GET /api/ebooks/:id/rating - User's rating for ebook
+- **Get Ebook Rating**: GET /api/ebooks/:id/rating - User's rating for ebook (returns 0 if unrated)
 - **Create/Update Rating**: POST /api/ebooks/:id/rating - Rate ebook (1-5 stars)
 - **Delete Rating**: DELETE /api/ebooks/:id/rating - Remove user's rating
 - **Get All Ratings**: GET /api/ebooks/:id/ratings - All ratings for ebook
@@ -47,7 +47,8 @@ Each request includes:
 
 - **Authentication Flow**: Register → Login → Use Bearer token for all other requests
 - **JWT Tokens**: Valid for 24 hours, include in `Authorization: Bearer <token>` header
-- **User Isolation**: Progress and data are user-specific
+- **User Isolation**: Progress, ratings, and data are user-specific
+- **Rating Behavior**: Get rating returns 0 when no rating exists (instead of 404)
 - **Variables**: Update `ebook_id` for testing specific ebooks
 - **Security**: Passwords hashed with bcrypt, unique email/username constraints
 - **JSON**: All requests/responses use JSON format

bruno/ebooks/Get Ebook Rating.bru

@@ -25,7 +25,7 @@ docs {
   **Path Parameters:**
   - `id` (string): Ebook UUID
 
-  **Response:**
+  **Response when rating exists:**
   - `id` (string): Rating UUID
   - `ebook_id` (string): Ebook UUID
   - `user_id` (string): User UUID
@@ -33,7 +33,13 @@ docs {
   - `created_at` (string): Creation timestamp
   - `updated_at` (string): Last update timestamp
 
+  **Response when no rating exists:**
+  - `ebook_id` (string): Ebook UUID
+  - `user_id` (string): User UUID
+  - `rating` (number): Always 0 (indicates no rating)
+
   **Error Responses:**
   - 401: Invalid authentication
-  - 404: Rating not found
+  
+  **Note:** This endpoint returns HTTP 200 with rating 0 when no rating exists, instead of HTTP 404.
 }