Kavita

Kavita is a self‑hosted, cross‑platform digital library that bundles a robust API surface with a modern, responsive web UI. From the developer’s point of view it is essentially a content‑delivery platform that serves e‑books, manga, comics and webtoons in a variety of archive formats (CBR/CBZ/ZIP/RAR, 7z, raw images) and document types (EPUB, PDF). The core of the application is written in C#/.NET 6+, exposing a RESTful API that powers the client‑side Single Page Application (SPA) built with React and TypeScript. The server is container‑friendly, with an official Docker image that mounts a persistent media volume and a SQLite or PostgreSQL database for metadata, making it trivial to integrate into Kubernetes, Docker‑Compose or even a bare‑metal VM.

• Backend: ASP.NET Core 6+, leveraging Entity Framework Core for ORM. The data layer can use SQLite (default) or PostgreSQL, enabling horizontal scaling via read replicas if needed. The API follows a clean separation of concerns: Controllers → Services → Repositories, and exposes HATEOAS‑style links for discoverability.
• Frontend: React + Redux Toolkit, with a theming engine that consumes JSON theme definitions from the /themes endpoint. The UI is built for mobile‑first with responsive CSS and a virtualized list component to handle large libraries without performance hits.
• Storage: Media files are stored on the host filesystem or any POSIX‑compatible storage. The application scans directories recursively, extracts metadata from filenames and external APIs (e.g., ComicVine, Kitsu) and caches it in the database.
• Authentication & Authorization: Supports local accounts, OIDC (OpenID Connect) providers, and role‑based access control. Roles can be scoped to libraries, allowing fine‑grained sharing (e.g., “read‑only” for a specific collection).

• Rich Metadata API: Endpoints such as /api/series, /api/chapters, and /api/files expose full metadata, including cover art URLs, volume/issue numbers, and custom tags. Developers can create smart filters programmatically by combining query parameters (?status=reading&rating>=4).
• Webhook & Event System: Custom webhooks can be registered to fire on events like SeriesUpdated, ChapterAdded, or UserCreated. This enables integration with external services (e.g., Slack, Home Assistant).
• Plugin Architecture: Kavita exposes a minimal plugin API that allows adding new metadata providers or readers. Plugins are simply .NET assemblies dropped into a plugins folder; the runtime loads them via reflection at startup.
• Download & Export: The /api/export endpoint returns a ZIP bundle of selected series, including all media and metadata, useful for backup or migration scripts.

• Containerization: The official Docker image (jvmilazz0/kavita) is Alpine‑based and supports multi‑arch builds. A typical deployment mounts two volumes: one for media (/media) and one for the database (/data). The container exposes ports 80 (HTTP) and 443 (HTTPS), with optional TLS termination handled by a reverse proxy.
• Scalability: While the application is designed for single‑instance use, it can be scaled horizontally behind a load balancer if the database is moved to PostgreSQL with proper connection pooling. The stateless nature of the API allows multiple replicas, and the media layer can be served from a shared NFS or cloud object store.
• Observability: Built‑in Prometheus metrics (/metrics) and structured logs (JSON) make it straightforward to integrate with Grafana or ELK stacks. Health checks (/health) are exposed for Kubernetes liveness/readiness probes.

• External APIs: Kavita+ (paid add‑on) extends the core with scrobbling, rating aggregation, and advanced metadata scraping. The API remains open for custom integrations; developers can write scripts that push data to /api/series or pull from /api/chapters.
• Webhooks: Any external system can subscribe to events via HTTPS callbacks. Payloads are JSON and include the full object state, making downstream processing deterministic.
• Theme & UI Customization: Themes are JSON files served from /themes. Developers can create custom themes or extend the UI by forking the React repo and adding new components, then building a Docker image that mounts the custom build into /webapp.

The project ships with comprehensive Swagger documentation (/swagger) and a well‑structured GitHub wiki that covers API usage, plugin development, and theme creation. The community is active on Discord and GitHub issues, providing rapid feedback for API changes or feature requests. The codebase follows SOLID principles and is continuously evaluated by SonarCloud, ensuring high maintainability and security ratings.

1. Personal Digital Library – Host a private server for family members, leveraging role‑based access to control who can read mature content.
2. Campus or Library Networks – Deploy on a campus intranet to provide students with free access to e‑books and comics, using OIDC for university credentials.
3. Manga/Comic Distribution – Small publishers can host a self‑managed catalog, expose an API to partner sites, and