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:
```bash
git clone <repository-url>
cd bookmann
```

2. Start all services:
```bash
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
```sql
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
```sql
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
```sql
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
```sql
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
```typescript
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
```typescript
interface UserProfile {
  id: string;
  email: string;
  username: string;
  created_at?: string;
}
```

#### ReadingProgress
```typescript
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

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

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

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

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

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

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

### Updating Progress (requires JWT token)

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

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

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

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

### Updating Progress (requires JWT token)

```bash
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:
```css
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

```bash
# 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.