Project snapshot

Status

Live self-hosted deployment for a private library.

Deployment

Private deployment with flexible local and cloud-backed media storage.

Data model

Ebooks, audiobooks, request workflows, series metadata, member roles, and a newer film/TV media module.

Quality

Unit tests, React Testing Library coverage, and 19 Playwright E2E spec files.

Technical proof

• Strict route/controller/service/repository layering with dependency-injected interfaces.
• BullMQ background jobs enrich records through Goodreads sync, R2 storage, and scraping fallbacks.
• Role-aware access, CSRF protection, rate limiting, and structured audit logs.

What it is

Bewks is a personal self-hosted library system for ebooks and audiobooks. It handles the full lifecycle of a digital collection: scanning local directories for EPUB, MOBI, and PDF files, extracting and normalizing metadata, organizing books by series and author, and serving them through a web UI with an in-browser reader. It is built for a single owner or small household, with role-based access (OWNER, ADMIN, MEMBER, GUEST) and a request workflow that lets members ask for titles to be added.

Architecture

The application follows a strict four-layer architecture — app/api routes delegate to controllers, controllers delegate to services, services delegate to repositories — with interfaces at each boundary for dependency injection. The database is SQLite in development and PostgreSQL in production, managed through Prisma with full migration history. File storage is dual-mode: books can live on local disk or in Cloudflare R2, with presigned URL delivery and a background sync worker. Background jobs use BullMQ with Redis, currently driving an async Goodreads metadata sync queue that enriches book records with covers and series data. A Playwright-based scraping fallback handles Goodreads pages that block automated HTTP clients.

Technical highlights

Authentication supports role-aware access, CSRF protection, structured audit logging, rate limiting, and a full session-management layer. A text-to-speech pipeline using Piper TTS can generate audiobooks from extracted ebook text, with admin controls and progress tracking. The project also has a dedicated Playwright smoke-test suite for release verification.

Where it’s at

A recent addition extended the library beyond books to include a media module backed by TMDB, IMDb (via GraphQL), and Rotten Tomatoes for film and TV metadata, with user-created watchlists and status tracking. The test suite covers unit tests in Vitest, component tests with React Testing Library, and 19 Playwright E2E spec files with parallel isolated-database runs.