Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

feat: Add comprehensive backend validation, toast notifications, and Tokyo Night theme

Browse Source 
- Backend: Add server-side validation with go-playground/validator/v10
- Frontend: Add toast notifications for API errors with @zerodevx/svelte-toast
- UI: Complete Tokyo Night theme redesign with modern animations
- Docs: Update COMPLETE_DOCUMENTATION.md and README.md with all enhancements
- Validation: Email format, password strength, and input sanitization
- UX: Real-time error feedback, loading states, and responsive design
This commit is contained in:
john-okeefe
2026-01-21 20:01:18 -05:00
parent 7448dfff30
commit 55c42f1f99
84 changed files with 7749 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
COMPLETE_DOCUMENTATION.md
+736
View File
@@ -0,0 +1,736 @@
# Ebook Reader and Library Manager - Complete Documentation
## Overview
A self-hosted ebook reader and library 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 library 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 library 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 the ebook reader system. For specific implementation details, refer to the source code comments and type definitions.