docs: Update documentation for role-based access control

- Update README.md with admin system documentation
- Add admin setup instructions and role permissions
- Update API endpoint documentation with access requirements
- Update Bruno collection to reflect admin-only operations
- Document shared library concept and security model
- Add comprehensive admin setup guide

bruno/README.md

@@ -17,18 +17,28 @@ This directory contains Bruno collection for testing the Bookmann API with compr
 - **Login User**: POST /api/auth/login - Authenticate (email or username)
 - **Get Profile**: GET /api/auth/profile - Get user info (requires token)
 
-### Ebooks (Protected - JWT Required)
-- **List Ebooks**: GET /api/ebooks - Paginated ebook list
-- **Get Ebook**: GET /api/ebooks/:id - Single ebook details
-- **Create Ebook**: POST /api/ebooks - Add new ebook
-- **Update Ebook**: PUT /api/ebooks/:id - Modify ebook metadata
-- **Delete Ebook**: DELETE /api/ebooks/:id - Remove ebook
+### Folders (Admin Only)
+- **Add Ebook Folder**: POST /api/auth/ebook-folders - Add folder for scanning (admin only)
+- **Get Ebook Folders**: GET /api/auth/ebook-folders - List configured folders (admin only)
+- **Delete Ebook Folder**: DELETE /api/auth/ebook-folders - Remove folder (admin only)
 
-### Reading Progress (Protected - JWT Required)
+### Ebooks (Mixed Access)
+- **List Ebooks**: GET /api/ebooks - Paginated ebook list (all authenticated users)
+- **Get Ebook**: GET /api/ebooks/:id - Single ebook details (all authenticated users)
+- **Create Ebook**: POST /api/ebooks - Add new ebook (admin only)
+- **Update Ebook**: PUT /api/ebooks/:id - Modify ebook metadata (admin only)
+- **Delete Ebook**: DELETE /api/ebooks/:id - Remove ebook (admin only)
+
+### Scanner (Admin Only)
+- **Scan Ebooks**: POST /api/scanner/scan - Scan configured folders (admin only)
+- **Start Scanner**: POST /api/scanner/start - Start real-time monitoring (admin only)
+- **Stop Scanner**: POST /api/scanner/stop - Stop monitoring (admin only)
+
+### Reading Progress (All Users)
 - **Get Reading Progress**: GET /api/ebooks/:id/progress - User's progress
 - **Update Reading Progress**: PUT /api/ebooks/:id/progress - Update progress
 
-### Ratings (Protected - JWT Required)
+### Ratings (All Users)
 - **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
@@ -47,8 +57,11 @@ 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, ratings, and data are user-specific
+- **Role System**: Two roles - 'admin' and 'user'. Admins can manage folders and ebooks, users can view/rate/track progress
+- **Shared Library**: All users can view the complete ebook collection, but only admins can modify it
+- **User Isolation**: Progress, ratings, and profile data are user-specific
 - **Rating Behavior**: Get rating returns 0 when no rating exists (instead of 404)
+- **Admin Setup**: First admin must be created by updating user role in database: `UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';`
 - **Variables**: Update `ebook_id` for testing specific ebooks
-- **Security**: Passwords hashed with bcrypt, unique email/username constraints
+- **Security**: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
 - **JSON**: All requests/responses use JSON format

bruno/ebooks/Create Ebook.bru

@@ -46,9 +46,9 @@ settings {
 docs {
   ## Create Ebook
   
-  Creates a new ebook entry in the library.
+  Creates a new ebook entry in the library. **Admin only operation.**
   
-  **Authentication:** Required (Bearer token)
+  **Authentication:** Required (Bearer token + Admin role)
   
    **Request Body:**
    - `title` (string, required): Book title
@@ -67,9 +67,12 @@ docs {
    - `publisher` (string, optional): Publisher name
    - `contributors` (string, optional): Additional contributors
   
-  **Response:** Created ebook object
+  **Response:** Created ebook object (with added_by_admin_id field)
   
   **Error Responses:**
   - 401: Invalid authentication
+  - 403: Forbidden (non-admin users)
   - 400: Invalid request data
+  
+  **Note:** Ebook will be automatically associated with the admin user who creates it.
 }

bruno/scanner/Scan Ebooks.bru

@@ -18,16 +18,16 @@ settings {
 docs {
   ## Scan Ebooks
   
-  Scans the user's configured ebook folders for ebooks and adds them to the database.
+  Scans configured ebook folders for ebooks and adds them to the database. **Admin only operation.**
   
   **Method:** POST
   
   **Endpoint:** /api/scanner/scan
   
-  **Authentication:** Required
+  **Authentication:** Required (Admin role required)
   
   **Request Body:**
-  - `folder_paths` (array of strings, optional): Array of folder paths to scan. If not provided, uses user's saved folders from Add Ebook Folder.
+  - `folder_paths` (array of strings, optional): Array of folder paths to scan. If not provided, uses configured folders from Add Ebook Folder.
   
   **Response:**
   - `message` (string): Success message
@@ -36,8 +36,11 @@ docs {
   - 200: Success
   - 400: Bad Request
   - 401: Unauthorized
+  - 403: Forbidden (non-admin users)
   
   **Usage:**
   - Without body: Scans all folders added via "Add Ebook Folder"
   - With folder_paths: Scans the specified paths directly (useful for testing)
+  
+  **Note:** All discovered ebooks will be associated with the admin user who initiated the scan.
 }

bruno/user/Add Ebook Folder.bru

@@ -24,20 +24,20 @@ settings {
 docs {
   ## Add Ebook Folder
   
-  Adds a new ebook folder for the authenticated user.
+  Adds a new ebook folder for scanning. **Admin only operation.**
   
   **Method:** POST
   
   **Endpoint:** /api/auth/ebook-folders
   
-  **Authentication:** Required
+  **Authentication:** Required (Admin role required)
   
   **Request Body:**
   - `folder_path` (string, required): Path to the ebook folder
   
   **Response:**
   - `id` (string): Folder ID
-  - `user_id` (string): User ID
+  - `user_id` (string): Admin user ID
   - `folder_path` (string): Folder path
   - `created_at` (string): Creation timestamp
   
@@ -45,5 +45,6 @@ docs {
   - 201: Created
   - 400: Invalid request
   - 401: Unauthorized
+  - 403: Forbidden (non-admin users)
   - 409: Folder already exists
 }