bookhoard/COMPLETE_DOCUMENTATION.md

Bookmann - Complete Documentation

Overview

Bookmann is a self-hosted ebook management system built with:

• Backend: Go API with Echo framework, PostgreSQL database with sqlc code generation, serving static frontend
• Frontend: Svelte with Vite, TypeScript, and TailwindCSS (built to static files)
• Database: PostgreSQL with migrations
• Deployment: Fully containerized with Docker and Docker Compose (single Go service)

Features

• Ebook management (CRUD operations)
• Reading progress tracking
• Responsive web interface
• RESTful API (accessible by web, mobile, etc.)
• Type-safe database queries with sqlc
• Modern UI with TailwindCSS
• Single-container deployment (Go serves everything)

Quick Start

Prerequisites

• Docker and Docker Compose
• Git (for cloning)

Running the Application

1. Clone the repository:

git clone <repository-url>
cd bookmann

2. Start all services:

docker-compose up --build

3. Access the application:

• Application: http://localhost:8765 (serves both frontend and API)
• Database: localhost:5432 (postgres/password)

Project Structure

bookmann/
├── backend/
│   ├── cmd/server/
│   │   └── main.go                 # Application entry point
│   ├── internal/
│   │   ├── config/
│   │   │   └── config.go           # Configuration management
│   │   ├── database/
│   │   │   ├── connection.go       # Database connection (pgx pool)
│   │   │   └── queries/
│   │   │       └── queries.sql     # SQL queries for sqlc
│   │   └── handlers/
│   │       └── ebook.go            # HTTP handlers
│   ├── migrations/
│   │   └── 001_create_tables.up.sql # Database schema
│   ├── Dockerfile                  # Backend Docker image (builds frontend)
│   ├── go.mod                      # Go dependencies
│   ├── go.sum
│   └── sqlc.yaml                   # sqlc configuration
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── api.ts              # API client with auth & error handling
│   │   │   ├── auth.ts             # Auth state management
│   │   │   └── toast.ts            # Toast notification utilities
│   │   ├── routes/
│   │   │   ├── login/
│   │   │   │   └── +page.svelte    # Login page (Tokyo Night theme)
│   │   │   ├── register/
│   │   │   │   └── +page.svelte    # Registration page (Tokyo Night theme)
│   │   │   ├── +layout.svelte      # Root layout with auth & toasts
│   │   │   └── +page.svelte        # Library page (Tokyo Night theme)
│   │   ├── app.css                 # Global styles with Tokyo Night theme
│   │   ├── app.d.ts                # TypeScript declarations
│   │   └── app.html                # HTML template with Inter font
│   ├── package.json                # Node dependencies with toast library
│   ├── svelte.config.js            # SvelteKit config (adapter-static)
│   ├── tailwind.config.js          # Tailwind config with Tokyo Night colors
│   ├── postcss.config.js           # PostCSS configuration (Tailwind v4)
├── docker-compose.yml              # Multi-service orchestration (db + backend only)
├── README.md                       # Basic README
└── .gitignore

Backend Documentation

Go Modules

Dependencies in go.mod:

• github.com/labstack/echo/v4 v4.11.3 - Web framework
• github.com/jackc/pgx/v5 v5.4.3 - PostgreSQL driver (pgx pool)
• github.com/golang-jwt/jwt/v5 v5.3.0 - JWT handling
• github.com/google/uuid v1.4.0 - UUID generation
• github.com/go-playground/validator/v10 v10.30.1 - Input validation
• golang.org/x/crypto v0.46.0 - Cryptographic functions (bcrypt)

Configuration

Environment variables (with defaults):

• SERVER_PORT=8765
• DATABASE_HOST=localhost
• DATABASE_PORT=5432
• DATABASE_USER=postgres
• DATABASE_PASSWORD=password
• DATABASE_NAME=ebookdb
• JWT_SECRET=your-secret-key
• UPLOAD_PATH=./uploads

Database Schema

Tables:

users

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

ebooks

CREATE TABLE ebooks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255),
    isbn VARCHAR(13),
    description TEXT,
    file_path VARCHAR(500) NOT NULL,
    file_size BIGINT,
    mime_type VARCHAR(100),
    cover_image_path VARCHAR(500),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

reading_progress

CREATE TABLE reading_progress (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ebook_id UUID NOT NULL REFERENCES ebooks(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    current_page INTEGER DEFAULT 0,
    total_pages INTEGER,
    last_read_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(ebook_id, user_id)
);

reading_progress

CREATE TABLE reading_progress (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ebook_id UUID NOT NULL REFERENCES ebooks(id) ON DELETE CASCADE,
    user_id VARCHAR(100) NOT NULL,
    current_page INTEGER DEFAULT 0,
    total_pages INTEGER,
    last_read_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(ebook_id, user_id)
);

Indexes:

• idx_users_email ON users(email)
• idx_users_username ON users(username)
• idx_ebooks_title ON ebooks(title)
• idx_ebooks_author ON ebooks(author)
• idx_reading_progress_ebook_id ON reading_progress(ebook_id)
• idx_reading_progress_user_id ON reading_progress(user_id)

Authentication

The application uses JWT (JSON Web Tokens) for authentication. The flow is:

1. Register or Login via /api/auth/register or /api/auth/login
2. Receive JWT token in response
3. Include token in Authorization: Bearer <token> header for protected requests
4. Token expires after 24 hours

Security Features:

• Passwords hashed with bcrypt (cost factor 10)
• JWT signed with configurable secret key
• User data properly isolated per authenticated user
• Unique constraints on email and username

API Endpoints

All endpoints now include comprehensive server-side validation. Invalid requests return detailed error messages in the response body.

Auth (Public)

POST /api/auth/register

• Body: { email: string, username: string, password: string }
• Returns: { token: string, user: UserProfile }

POST /api/auth/login

• Body: { login: string, password: string } (login can be email or username)
• Returns: { token: string, user: UserProfile }

GET /api/auth/profile (requires JWT)

• Returns: UserProfile

Ebooks (requires JWT)

GET /api/ebooks

• Query params: limit (default: 20), offset (default: 0)
• Returns: Array of ebook objects

GET /api/ebooks/:id

• Path param: id (UUID)
• Returns: Single ebook object

POST /api/ebooks

• Body: Ebook data (JSON)
• Required fields: title, file_path
• Returns: Created ebook object

PUT /api/ebooks/:id

• Path param: id (UUID)
• Body: Updated ebook data (JSON)
• Returns: Updated ebook object

DELETE /api/ebooks/:id

• Path param: id (UUID)
• Returns: 204 No Content

Reading Progress (requires JWT)

GET /api/ebooks/:id/progress

• Path param: ebookId
• Returns: Reading progress object for authenticated user

PUT /api/ebooks/:id/progress

• Path param: ebookId
• Body: { current_page: number, total_pages?: number }
• Returns: Updated progress object for authenticated user

Type Definitions

Ebook

interface Ebook {
  id: string;
  title: string;
  author: string | null;
  isbn: string | null;
  description: string | null;
  file_path: string;
  file_size: number | null;
  mime_type: string | null;
  cover_image_path: string | null;
  created_at: string;
  updated_at: string;
}

UserProfile

interface UserProfile {
  id: string;
  email: string;
  username: string;
  created_at?: string;
}

ReadingProgress

interface ReadingProgress {
  ebook_id: string;
  user_id: string;
  current_page: number;
  total_pages: number | null;
  last_read_at: string;
}

Frontend Documentation

SvelteKit Setup

• Framework: SvelteKit with TypeScript
• Build tool: Vite
• Styling: TailwindCSS
• Authentication: JWT-based with localStorage token storage
• State Management: Svelte stores for reactive auth state
• Routing: Protected routes with auth-based conditional rendering
• UI Components: Custom components with Tailwind classes

Key Files

src/lib/api.ts

API client functions for all backend endpoints with JWT authentication and error handling:

• Auth functions: registerUser(), loginUser(), getUserProfile()
• Ebook functions: fetchEbooks(), fetchEbook(), createEbook(), updateEbook(), deleteEbook()
• Progress functions: fetchReadingProgress(), updateReadingProgress() (user-specific via token)
• Error handling: Automatic toast notifications for API errors with parsed error messages
• All functions automatically include Bearer token headers when authenticated

src/lib/auth.ts

Authentication state management store:

• Reactive auth state with Svelte stores
• JWT token persistence in localStorage
• Login/logout functionality
• Auth state initialization

src/lib/toast.ts

Toast notification utilities:

• showError() - Display error toasts with Tokyo Night red styling
• showSuccess() - Display success toasts with Tokyo Night green styling
• Integrated with API error handling for automatic user feedback

src/routes/login/+page.svelte

Login page with form validation and error handling

src/routes/register/+page.svelte

Registration page with password confirmation and validation

src/routes/+layout.svelte

Root layout with authentication:

• Auth state initialization and management
• Conditional rendering based on login status
• Navigation header with user info and logout
• Auth forms for unauthenticated users

Styling

Tokyo Night Theme with TailwindCSS:

• Color Palette: Custom Tokyo Night colors (#1a1b26 backgrounds, #7aa2f7 accents)
• Typography: Inter font family loaded from Google Fonts
• Animations: Custom fade-in and slide-in animations
• Components: Pre-built button, card, input, and navigation styles
• Dark Theme: Complete dark mode implementation with proper contrast
• Responsive Design: Mobile-first approach with breakpoint optimizations
• Interactive Elements: Hover effects, focus states, and smooth transitions

Authentication Flow

Frontend Implementation:

• State Management: Reactive auth store with login/logout actions
• Token Persistence: JWT tokens stored in localStorage with session persistence
• Route Protection: Layout component handles auth-based conditional rendering
• API Integration: All API calls include auth headers automatically
• Form Validation: Client-side validation with error display
• User Experience: Seamless transitions between auth states

Docker Configuration

Backend Dockerfile

• Multi-stage build with Go and Node.js stages
• Alpine Linux for small final image
• Frontend built to static files during Docker build
• sqlc code generation during build
• Binary compilation with CGO disabled
• Static files copied to final image

Docker Compose Services

db (PostgreSQL)

• Image: postgres:15-alpine
• Health check with pg_isready
• Volume for data persistence
• Init scripts from migrations folder

backend (Go API + Static Frontend)

• Build from backend/Dockerfile
• Environment variables for configuration
• Health check for application availability
• Depends on database health
• Volume for uploads directory
• Serves both API and static frontend files

Networking

Services communicate via Docker networks:

• backend serves static files for frontend and API endpoints
• backend connects to db:5432
• All services restart automatically on failure

Development Setup

Backend Development

cd backend
go mod tidy
go run github.com/sqlc-dev/sqlc/cmd/sqlc@latest generate
go run cmd/server/main.go

Frontend Development

For development, run the frontend separately:

cd frontend
npm install
npm run dev -- --open

Note: For production, frontend is built statically and served by the Go backend. API calls should proxy to the backend (e.g., via Vite proxy in dev).

Database Development

# Connect to database
psql -h localhost -p 5432 -U postgres -d ebookdb

# Run migrations manually (if needed)
# Migrations run automatically in Docker

Deployment

Production Considerations

1. Environment Variables: Change default passwords, JWT secret, and database credentials
2. Database: Use managed PostgreSQL in production with connection pooling
3. File Storage: Implement cloud storage for ebook files (S3, etc.)
4. Authentication: JWT secrets should be strong and rotated regularly
5. HTTPS: Configure SSL certificates for secure transmission
6. Rate Limiting: Add rate limiting for auth endpoints to prevent brute force
7. User Management: Consider email verification, password reset, account locking
8. Monitoring: Add logging and monitoring for auth failures
9. Backup: Regular database backups including user data

Scaling

• Database can be moved to separate instance
• Backend can be scaled horizontally with load balancer
• Frontend static files can be served from CDN
• File storage can use cloud storage (S3, etc.)

User Journey

Complete User Flow

1. Registration: User visits /register, fills form, receives JWT token
2. Login: User can login with email or username, receives JWT token
3. Token Storage: Frontend stores JWT in localStorage
4. API Access: All subsequent API calls include Bearer token
5. Library Access: User sees their ebook collection with personal reading progress
6. Progress Tracking: Reading progress is automatically associated with user
7. Session Management: User stays logged in across browser sessions
8. Logout: User can logout, clearing token and redirecting to login

Security Features

• Password Hashing: Bcrypt with cost factor 10
• JWT Tokens: 24-hour expiration, signed with configurable secret
• User Isolation: All data is user-specific and properly segregated
• Session Persistence: Secure token storage with automatic validation
• API Protection: All sensitive operations require valid authentication

API Usage Examples

Registering a User

curl -X POST http://localhost:8765/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "testuser",
    "password": "securepassword"
  }'

Logging in a User

curl -X POST http://localhost:8765/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "login": "user@example.com",
    "password": "securepassword"
  }'

Creating an Ebook (requires JWT token)

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8765/api/ebooks \
  -d '{
    "title": "Sample Book",
    "author": "Sample Author",
    "file_path": "/uploads/sample.epub",
    "file_size": 1024000,
    "mime_type": "application/epub+zip"
  }'

Getting Reading Progress (requires JWT token)

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8765/api/ebooks/123e4567-e89b-12d3-a456-426614174000/progress

Updating Progress (requires JWT token)

curl -X PUT -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8765/api/ebooks/123e4567-e89b-12d3-a456-426614174000/progress \
  -d '{"current_page": 45, "total_pages": 200}'

Register User

curl -X POST http://localhost:8765/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "testuser",
    "password": "securepassword"
  }'

Login User

curl -X POST http://localhost:8765/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "login": "user@example.com",
    "password": "securepassword"
  }'

Getting Reading Progress (requires JWT token)

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8765/api/ebooks/123e4567-e89b-12d3-a456-426614174000/progress

Updating Progress (requires JWT token)

curl -X PUT -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8765/api/ebooks/123e4567-e89b-12d3-a456-426614174000/progress \
  -d '{"current_page": 45, "total_pages": 200}'

Recent Changes (Complete Multi-User Auth System)

As of the latest updates, the application has been completely transformed into a full multi-user ebook management system:

• Multi-User Authentication: Complete user system with registration/login, supporting both email and username login, JWT-based sessions, and bcrypt password hashing
• Security: Passwords stored with industry-standard bcrypt hashing, JWT tokens for API access, user data isolation, secure token management
• API Evolution: Auth endpoints added, reading progress now user-specific (removed :userId params), all ebook operations require authentication
• Frontend Auth Integration: Svelte frontend fully updated with login/register forms, JWT token management in localStorage, reactive auth state store, protected routes with automatic redirects
• User Experience: Seamless auth flow with form validation, session persistence, user dashboard, logout functionality
• Architecture: Single Go service serving both static frontend and API, no Node.js dependency
• Database: New users table, updated reading_progress with user foreign keys, comprehensive indexing
• Testing: Bruno collection updated with auth flows and Bearer token authentication
• Cleanup: Removed obsolete Docker files for frontend containerization

Latest Updates (Enhanced Validation, UI/UX & Tokyo Night Theme)

Backend API Validation Enhancement

• Server-Side Validation: Added comprehensive input validation using github.com/go-playground/validator/v10
• Request Validation: All API endpoints now validate request data before processing
• Error Responses: Detailed validation error messages returned for invalid requests
• Security: Prevents malformed data from reaching the database layer

Validation Rules Added:

• User Registration: Email format validation, username length (3-50 chars), password minimum length (6+ chars)
• User Login: Required email/username and password fields
• Ebook Creation: Required title and file_path, minimum title length (1-500 chars), optional file size validation
• Ebook Updates: Title validation when provided, cover image path validation
• Reading Progress: Required current_page (≥0), optional total_pages (≥1)

Frontend Toast Notifications

• Error Notifications: Real-time toast popups for all API errors using @zerodevx/svelte-toast
• User Feedback: Immediate visual feedback for failed operations (login, registration, CRUD operations)
• Error Parsing: Automatically extracts and displays backend validation messages
• Non-Intrusive Design: Toasts appear without disrupting user workflow

Tokyo Night Theme Redesign

• Complete UI Overhaul: Transformed the entire frontend with the popular Tokyo Night dark theme
• Color Palette: Deep blue backgrounds (#1a1b26), cyan accents (#7dcfff), and carefully chosen contrast colors
• Modern Design: Gradient backgrounds, smooth animations, and professional card-based layouts
• Enhanced Typography: Inter font family for improved readability
• Interactive Elements: Hover effects, focus states, and smooth transitions throughout

Tokyo Night Color Scheme:

Background: #1a1b26 (dark blue-gray)
Secondary Background: #16161e (darker blue)
Highlights: #292e42 (medium blue-gray)
Foreground: #a9b1d6 (light blue-gray)
Accent Blue: #7aa2f7
Accent Cyan: #7dcfff
Accent Red: #f7768e
Accent Green: #9ece6a
Accent Purple: #bb9af7

Enhanced User Experience Features

• Loading States: Beautiful animated spinners during data fetching
• Form Validation: Real-time client-side validation with visual feedback
• Responsive Design: Optimized for all screen sizes with mobile-first approach
• Animation System: Fade-in and slide-in animations for page transitions
• Error Handling: Comprehensive error states with user-friendly messages
• Empty States: Attractive placeholders when no data is available
• Visual Hierarchy: Clear information architecture with proper spacing and typography

Technical Improvements

• Performance: Optimized CSS compilation with direct color values for better build performance
• Accessibility: Proper contrast ratios and focus management
• Code Organization: Clean separation of concerns with utility functions
• Type Safety: Full TypeScript integration with proper error typing
• Build Optimization: Efficient static file generation and caching

Updated Dependencies

• Backend: Added github.com/go-playground/validator/v10 for validation
• Frontend: Added @zerodevx/svelte-toast for notifications
• Fonts: Added Google Fonts Inter for enhanced typography
• Tailwind: Extended configuration with custom animations and Tokyo Night colors

User Interface Components

• Authentication Pages: Redesigned login/register forms with card layouts and icons
• Library View: Grid-based ebook display with hover effects and metadata
• Navigation: Clean header with user information and logout functionality
• Loading Screens: Beautiful animated loading states
• Error Displays: User-friendly error messages with appropriate styling
• Toast Notifications: Non-intrusive error feedback system

This comprehensive update transforms the application into a modern, professional ebook management system with excellent user experience, robust validation, and beautiful dark theme design.

Troubleshooting

Common Issues

1. Database Connection Failed

   • Check if PostgreSQL container is running
   • Verify DATABASE_* environment variables
   • Check database logs: docker-compose logs db

2. Application Not Accessible

   • Verify backend container is running
   • Check backend logs: docker-compose logs backend
   • Test health endpoint: curl http://localhost:8765/

3. Authentication Issues

   • Verify JWT_SECRET environment variable is set
   • Check token expiration (24 hours)
   • Ensure Bearer token format: Authorization: Bearer <token>
   • Test auth endpoints first: /api/auth/register, /api/auth/login
   • Check validation errors in API responses (frontend shows toast notifications)

4. Validation Errors

   • Frontend displays validation errors via toast notifications
   • Check API response body for detailed error messages
   • Ensure request data matches validation rules (email format, password length, etc.)

5. Frontend Not Loading

   • Check backend logs for static file serving
   • Verify frontend built correctly in Docker
   • Check browser console for errors
   • Ensure Tokyo Night theme CSS compiled properly

6. API Authorization Errors

   • Confirm JWT token is valid and not expired
   • Check middleware logs for auth failures
   • Verify protected endpoints use correct HTTP methods

7. Build Failures

   • Clear Docker cache: docker system prune -a
   • Rebuild: docker-compose up --build --force-recreate

Logs

# All services
docker-compose logs

# Specific service
docker-compose logs backend
docker-compose logs frontend
docker-compose logs db

# Follow logs
docker-compose logs -f backend

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with proper testing
4. Submit a pull request

License

MIT License - see LICENSE file for details

Future Enhancements

• Email verification for user registration
• Password reset functionality
• User profile management (update email/username, change password)
• Email notifications (welcome, password reset, etc.)
• User roles and permissions (admin, regular user)
• Ebook file upload and processing with validation
• EPUB/PDF reader component with bookmarking
• Advanced search and filtering (by author, genre, etc.)
• Categories and tags for ebooks
• Reading statistics and analytics dashboard
• Social features (sharing reading lists, reviews)
• Mobile app development (React Native/Flutter)
• Cloud storage integration (S3, Google Drive)
• Backup and restore functionality
• Admin panel for user management
• OAuth integration (Google, GitHub, Apple login)
• Two-factor authentication (2FA)
• Session management and device tracking

---

This documentation covers the complete setup, configuration, and usage of Bookmann. For specific implementation details, refer to the source code comments and type definitions.