docs: update comprehensive API documentation and project guides
This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
This commit is contained in:
@@ -30,6 +30,7 @@ bookhoard/
|
||||
### Backend Components
|
||||
|
||||
**Handlers** (`internal/handlers/`):
|
||||
|
||||
- `auth.go` - Authentication & user management
|
||||
- `library.go` - Library CRUD operations
|
||||
- `scanner.go` - Media scanning operations
|
||||
@@ -51,6 +52,7 @@ bookhoard/
|
||||
- `context.go` - Handler context utilities
|
||||
|
||||
**Middleware** (`internal/middleware/`):
|
||||
|
||||
- `device_auth.go` - Device authentication
|
||||
- `device_rate_limiter.go` - Device-specific rate limiting
|
||||
- `error_handler.go` - Global error handling
|
||||
@@ -62,6 +64,7 @@ bookhoard/
|
||||
- `transaction.go` - Database transaction middleware
|
||||
|
||||
**Services** (`internal/services/`):
|
||||
|
||||
- `library_service.go` - Library operations
|
||||
- `media_scanner.go` - File scanning & metadata extraction
|
||||
- `worker.go` - Job queue worker pool
|
||||
@@ -71,6 +74,7 @@ bookhoard/
|
||||
- `book_matching.go` - Book matching algorithms
|
||||
|
||||
**Sync Framework** (`internal/sync/`):
|
||||
|
||||
- `queue.go` - Sync queue processor
|
||||
- `progress.go` - Universal progress format
|
||||
- `websocket.go` - Real-time sync broadcast
|
||||
@@ -80,6 +84,7 @@ bookhoard/
|
||||
### Database Schema
|
||||
|
||||
**Core Tables**:
|
||||
|
||||
- `users` - User accounts with authentication and settings
|
||||
- `libraries` - Library definitions
|
||||
- `library_types` - Media type definitions (ebooks, comics, manga)
|
||||
@@ -105,6 +110,7 @@ bookhoard/
|
||||
- `refresh_tokens` - JWT refresh token storage
|
||||
|
||||
**Database Functions**:
|
||||
|
||||
- `normalize_isbn()` - ISBN format normalization
|
||||
- `detect_format_group()` - Detect format group (reflowable, fixed_layout, comic_archive)
|
||||
- `convert_progress()` - Convert progress between format groups
|
||||
@@ -114,6 +120,7 @@ bookhoard/
|
||||
### Technology Stack
|
||||
|
||||
**Backend**:
|
||||
|
||||
- Go 1.25+
|
||||
- Echo v4 - HTTP framework
|
||||
- pgx v5 - PostgreSQL driver
|
||||
@@ -122,18 +129,21 @@ bookhoard/
|
||||
- bcrypt - Password hashing
|
||||
|
||||
**Frontend**:
|
||||
|
||||
- Templ - HTML templating with Go
|
||||
- HTMX - Dynamic interactions
|
||||
- Tailwind CSS - Styling
|
||||
- TypeScript - Frontend logic
|
||||
|
||||
**Database**:
|
||||
|
||||
- PostgreSQL 15+
|
||||
- 30+ tables
|
||||
- 50+ indexes
|
||||
- JSONB for complex data
|
||||
|
||||
**Testing**:
|
||||
|
||||
- Testify - Testing framework
|
||||
- Bruno - API testing
|
||||
- 30+ integration test files
|
||||
@@ -201,6 +211,7 @@ go run cmd/server/main.go
|
||||
### Development Workflow
|
||||
|
||||
**Backend Development**:
|
||||
|
||||
```bash
|
||||
# Watch mode for Go (requires air or similar)
|
||||
air
|
||||
@@ -211,18 +222,21 @@ go build -o bookhoard cmd/server/main.go
|
||||
```
|
||||
|
||||
**Frontend Development**:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm run dev # Watch mode for TypeScript/CSS
|
||||
```
|
||||
|
||||
**Database Changes**:
|
||||
|
||||
1. Edit `database/schema/schema.sql`
|
||||
2. Edit `internal/database/queries/queries.sql`
|
||||
3. Run: `cd internal/database && sqlc generate`
|
||||
4. Restart server
|
||||
|
||||
**Template Changes**:
|
||||
|
||||
1. Edit `templates/*.templ`
|
||||
2. Run: `cd templates && templ generate`
|
||||
3. Restart server (templates auto-reload in dev mode)
|
||||
@@ -273,6 +287,7 @@ bruno run bruno/sync-kobo/
|
||||
### Test Configuration
|
||||
|
||||
Environment variables for testing:
|
||||
|
||||
- `TEST_MODE=true` - Enable test mode (disables rate limiting)
|
||||
- `RATE_LIMIT_ENABLED=false` - Disable rate limiting
|
||||
- `REQUESTS_PER_MINUTE=1000` - Increase rate limit
|
||||
@@ -284,6 +299,7 @@ Environment variables for testing:
|
||||
Integration tests automatically clean up libraries with "test" in the name (case-insensitive).
|
||||
|
||||
**⚠️ IMPORTANT**: Do not use "test" in library names if you want to keep them!
|
||||
|
||||
- Libraries containing "test" (e.g., "My Test Library", "Test Library 1") will be deleted by test cleanup
|
||||
- Use names like "Development Library", "Staging Books", or "Personal" for libraries you want to keep
|
||||
- This ensures your manual test data persists between test runs
|
||||
@@ -357,11 +373,13 @@ podman-compose build --no-cache
|
||||
### Environment Variables
|
||||
|
||||
Required for production:
|
||||
|
||||
- `JWT_SECRET` - 64-byte random string (generate: `openssl rand -hex 32`)
|
||||
- `DBPASS` - Strong database password (generate: `openssl rand -hex 16`)
|
||||
- `BASE_URL` - Public URL (e.g., https://bookhoard.example.com)
|
||||
|
||||
Optional:
|
||||
|
||||
- `HTTPS_PROXY` - If behind reverse proxy
|
||||
|
||||
**Note**: Conversion service, rate limiting, and other operational settings have defaults in `docker-compose.yml` and can be overridden via `.env` if needed.
|
||||
@@ -369,6 +387,7 @@ Optional:
|
||||
### Performance Tuning
|
||||
|
||||
**PostgreSQL Settings**:
|
||||
|
||||
```sql
|
||||
-- In postgresql.conf
|
||||
shared_buffers = 256MB
|
||||
@@ -385,6 +404,7 @@ max_wal_size = 4GB
|
||||
```
|
||||
|
||||
**Go Settings**:
|
||||
|
||||
- GOMAXPROCS = number of CPU cores
|
||||
- Worker pool concurrency: 3 (configurable in services/worker.go)
|
||||
|
||||
@@ -403,19 +423,23 @@ DEBUG=true
|
||||
### Common Issues
|
||||
|
||||
**Database Connection Errors**:
|
||||
|
||||
- Check PostgreSQL is running
|
||||
- Verify DATABASE_HOST and DATABASE_PORT
|
||||
- Check firewall settings
|
||||
|
||||
**Rate Limiting During Development**:
|
||||
|
||||
- Enable test mode: `TEST_MODE=true RATE_LIMIT_ENABLED=false`
|
||||
- Or increase limit: `REQUESTS_PER_MINUTE=1000`
|
||||
|
||||
**Template Not Updating**:
|
||||
|
||||
- Run `templ generate` in templates/ directory
|
||||
- Restart server
|
||||
|
||||
**Database Queries Not Working**:
|
||||
|
||||
- Run `sqlc generate` in internal/database/
|
||||
- Check generated code in `queries.sql.go`
|
||||
- Verify SQL syntax in `queries.sql`
|
||||
|
||||
Reference in New Issue
Block a user