Atsumeru

Atsumeru is a self‑hosted media server focused on manga, comics, and light novels. From a developer’s standpoint it functions as an extensible library manager that ingests common archive formats (CBZ, CBR, CB7, PDF, ePub, FB2, DjVu) and exposes a robust REST API for CRUD operations on books, series, users, and metadata. The core of the application is a Java 17 Spring Boot backend that serializes domain objects into a relational database (PostgreSQL or MySQL) while providing an optional in‑memory H2 mode for lightweight deployments. The API is documented with Swagger UI, allowing developers to quickly generate client SDKs in any language.

• Language & Framework: Java 17, Spring Boot 3.x, JPA/Hibernate for persistence.
• API Layer: Exposes a versioned REST surface (/api/v1/...) with JSON payloads and multipart support for file uploads. Swagger UI serves at /swagger-ui/index.html.
• Data Layer: Uses a relational schema with tables for Series, Volumes, Users, Categories, and Metadata. The schema is auto‑generated via Flyway migrations, ensuring repeatable deployments.
• File Storage: The server stores archives in a configurable directory tree. A background worker scans this tree, extracts metadata from ComicInfo.xml or the proprietary book_info.json, and indexes entries into the database.
• Security: Implements JWT‑based authentication, role‑based access control, and optional LDAP integration for enterprise environments.

• Metadata Import/Export: Parse and generate ComicInfo.xml and a custom book_info.json. This allows round‑tripping metadata between Atsumeru and other cataloging tools.
• Categorization: Auto‑categories based on file naming conventions, custom categories defined via UI or API, and meta‑categories that aggregate multiple tags.
• Multi‑User Support: Separate reading histories, fine‑grained ACLs, and per‑user download quotas.
• Download Service: API endpoints to bundle an entire series into a single ZIP, streamable for client consumption.
• Webhook & Plugin Hooks: Exposes webhooks on events (e.g., new upload, metadata update) and a simple plugin interface for extending the import pipeline or adding custom UI panels.

• Containerization: Official Docker image (atsumerudev/atsumeru) is available on Docker Hub. A single container can run the full stack, with volumes for /data (archives) and /config (database files).
• Scalability: Horizontal scaling is achievable by running multiple instances behind a load balancer, sharing the same database and file store (e.g., NFS or S3‑compatible storage). The stateless API layer allows easy replication.
• Self‑Hosting Requirements: Minimum 4 GB RAM, Java Runtime (OpenJDK 17), and a relational database. Docker users can omit the DB step by using SQLite in embedded mode for quick demos.

• SDK Generation: Swagger Codegen or OpenAPI Generator can produce client libraries in Java, Kotlin, TypeScript, Python, etc.
• Custom Importers: The import worker can be extended by implementing a simple Java interface; new file types or metadata parsers can be plugged in without modifying core code.
• Webhooks: External services (e.g., CI pipelines, media servers) can subscribe to events via configurable URLs.
• UI Customization: The web UI is built with Thymeleaf and can be overridden by providing custom templates in the /templates directory.

• Documentation: Comprehensive API docs via Swagger, a dedicated installation guide for JAR and Docker setups, and an online wiki.
• Community: Active GitHub repository with issue tracking, pull requests, and a Discord channel for real‑time support.
• Configuration: All settings are exposed through application.yml and environment variables, enabling seamless integration into CI/CD pipelines or Kubernetes ConfigMaps.

1. Personal Library Server – A hobbyist can host a private collection, access it from Android or Windows clients, and sync reading progress across devices.
2. Enterprise Knowledge Base – Companies managing comic‑based training material can leverage multi‑user ACLs and audit logs.
3. API‑Driven Service – Developers can build custom readers or aggregation services that consume Atsumeru’s REST endpoints, integrating with other media platforms.

• Open Source & License: MIT‑licensed, allowing unrestricted commercial use.
• Performance: Spring Boot’s non‑blocking web layer and efficient JPA mappings keep response times low even with thousands of volumes.
• Flexibility: The plugin architecture and webhook system let developers tailor the workflow to niche requirements.
• Cross‑Platform Clients: Native apps for Windows, Linux, macOS, and Android reduce the need to build custom front‑ends.

Atsumeru delivers a developer‑friendly, self‑hosted solution for managing serialized media, combining a clean API surface with extensible architecture and robust deployment options.