BookLogr

BookLogr is a lightweight, self‑hosted web service that turns a collection of e‑books into a searchable, trackable library. At its core it exposes a RESTful API and a single‑page application that lets users query book metadata, maintain reading lists, record progress, and expose a public profile. The application is built to run on any modern Linux host with minimal external dependencies, making it a natural fit for home servers, Docker stacks, or cloud VMs.

Technical Stack & Architecture

• Backend – Implemented in Go (v1.22+), the server uses the net/http standard library combined with the chi router for concise route definitions. Business logic is split into distinct packages: catalog (OpenLibrary integration), library (CRUD for books, lists, notes), and export (CSV/JSON/HTML generation).
• Database – Supports SQLite as the default embedded store for quick local deployments, and PostgreSQL for production‑grade scaling. The ORM layer is powered by sqlc, which generates type‑safe query code from SQL templates, ensuring compile‑time safety.
• Frontend – A React (v18) SPA served as a static bundle from the /public directory. It communicates with the backend solely over JSON, using long‑polling for real‑time updates (e.g., progress pushes to Mastodon).
• External Services – Book metadata is fetched from OpenLibrary via their public API. Optional integration with Mastodon requires a user OAuth token; the server handles token storage securely in the database.

The architecture follows a classic three‑tier model: API layer → business logic → persistence, with a thin presentation layer that could be swapped out without touching core code.

Core Capabilities & Developer APIs

• Book Discovery – GET /api/books?query=... queries OpenLibrary and returns enriched metadata.
• List Management – CRUD endpoints for predefined lists (Reading, Already Read, To Be Read) and custom lists via /api/lists.
• Progress Tracking – PATCH /api/books/:id/progress updates current page and optionally triggers a webhook to Mastodon.
• Export – /api/export supports application/json, text/csv, and text/html. The exporter is pluggable; developers can add new formats by implementing the Exporter interface.
• Webhooks & Events – The API emits events on book addition or progress updates, which can be consumed by external services.

All endpoints are documented in OpenAPI format and available under /docs. The server also exposes a health‑check endpoint (/healthz) for orchestration tools.

Deployment & Infrastructure

BookLogr is designed for containerized deployment. The official Docker image (ghcr.io/mozzo1000/booklogr:latest) bundles the Go binary and static assets, exposing port 3000. It requires a writable volume for the database file (SQLite) or a PostgreSQL host. For production, Docker Compose or Kubernetes manifests are provided in the repo’s deploy directory. The application scales horizontally by running multiple replicas behind a load balancer; the stateless API layer and shared database ensure consistency across instances.

Integration & Extensibility

• Plugin System – Developers can extend BookLogr by implementing the Plugin interface, which hooks into lifecycle events (e.g., after book import). Plugins are loaded from a /plugins directory at startup.
• API Extensions – Custom endpoints can be added by registering new handlers with the chi router; middleware for authentication or rate‑limiting can be injected globally.
• Webhooks – External services may subscribe to events via a configurable webhook URL, receiving JSON payloads for book additions or progress changes.
• Theme & UI – The React frontend is built with CSS modules; developers can swap themes by replacing the static assets or editing the SCSS variables.

Developer Experience

Configuration is handled through environment variables (DATABASE_URL, OPENLIBRARY_API_KEY, MASTODON_ACCESS_TOKEN). The README and wiki contain comprehensive guides, while the OpenAPI spec provides a single source of truth for API contracts. The community is active on GitHub issues and the dedicated translation wiki, ensuring prompt support for language or feature requests. The Apache 2.0 license allows commercial use without licensing fees, and the open‑source codebase encourages contributions.

Use Cases

• Home Library Management – A hobbyist can run BookLogr on a Raspberry Pi, maintaining an offline catalog that syncs with OpenLibrary.
• Developer Portfolios – Programmers can expose a public profile of books read, integrating with Mastodon or GitHub Gists.
• Educational Environments – A small school can host BookLogr on a shared server to track student reading lists and progress.
• API‑First Integration – Teams building e‑book readers or study aids can consume BookLogr’s API to import and sync reading data.

Advantages Over Alternatives

• Performance – Go’s compiled binaries deliver low latency; SQLite keeps the footprint tiny for single‑user setups.
• Flexibility –