Koillection

Koillection is a self‑hosted, PHP‑based collection manager designed to catalogue physical items such as books, DVDs, stamps, and games. At its core, the application exposes a rich REST API that mirrors all CRUD operations on collections, items, tags, and wishlists. The front‑end is a modern Progressive Web App built with Vue.js (or similar), enabling offline use, push notifications, and native‑app feel on mobile devices. From a developer’s standpoint, the project is intentionally agnostic about metadata sources; it offers a pluggable scraper framework that lets you inject custom HTML parsers or external APIs, making it suitable for niche collections that lack public data feeds.

• Backend: Laravel 9 (or newer) – the framework provides Eloquent ORM, authentication scaffolding, and a robust routing layer for the API. The business logic is split into service classes that handle collection validation, item import, and permission checks.
• Database: Supports PostgreSQL ≥10.0, MariaDB/MySQL ≥10.0/8.0. The schema is normalized with a many‑to‑many relationship between items and tags, and a polymorphic association for “signs” (notes, images). Migrations are versioned and can be run inside Docker Compose or a CI pipeline.
• Front‑end: Vue 3 + Pinia for state management, using Axios to consume the REST endpoints. The PWA is registered with a service worker that caches API responses and static assets, enabling offline browsing.
• Scraper Engine: A PHP service that accepts a URL and a user‑defined parser class. Parsers are simple classes implementing an interface, allowing developers to inject any HTML scraping logic or external API calls without touching the core.

• RESTful API: Endpoints for collections (/api/collections), items, tags, wishlists, and user management. Supports pagination, filtering by tag or collection, and bulk import via CSV/JSON.
• Role‑Based Access Control: Fine‑grained permissions (view, edit, delete) that can be assigned per collection or globally. This is exposed via the API and enforced by middleware.
• Webhook Support: Post‑request hooks that notify external services when items are added or updated. The webhook payload is customizable through a JSON schema.
• PWA Features: Service worker, manifest, and “Add to Home Screen” prompts. Developers can override the default icons or add custom splash screens.
• Extensibility: The scraper framework, webhook handlers, and permission gates are all hookable via Composer autoload. You can publish the config files (koillection.php) and override any service provider.

Koillection ships with a ready‑to‑use docker-compose.yml that defines three services: the web container (PHP-FPM + Nginx), a PostgreSQL database, and Redis for caching. Docker Swarm or Kubernetes manifests are also available in the repo’s deploy/ folder, facilitating horizontal scaling of the API layer. The application is stateless; session data can be stored in Redis or JWT‑based tokens, making it straightforward to run multiple instances behind a load balancer.

• Plugin System: Any Composer package can be added as a plugin by implementing the Koillection\PluginInterface. The framework automatically loads these during bootstrapping, allowing developers to extend functionality (e.g., adding a Goodreads importer).
• API Documentation: Swagger/OpenAPI specs are generated automatically from route annotations, enabling quick integration into third‑party apps.
• Webhooks & Callbacks: External services can subscribe to events such as item.created or collection.updated. The payload includes the full entity representation, making it easy to sync with inventory systems or analytics dashboards.

The codebase follows PSR‑4 autoloading, with clear separation of concerns. Inline PHPDoc comments and a comprehensive README provide guidance on extending the scraper engine or adding new API endpoints. The community is active on GitHub, with issue templates for feature requests and a wiki that documents the architecture. Licensing is MIT, ensuring no restrictive copyleft constraints for commercial deployments.

• Home Libraries: A hobbyist can host Koillection locally, import their book list via a custom scraper that pulls from a local CSV, and share the collection with family members through invite links.
• Small Retailers: A used‑book shop can expose a read‑only API to their storefront, allowing customers to browse inventory without exposing sensitive data.
• Personal Projects: Developers building a custom mobile app can consume the REST API, leveraging the PWA as a quick prototype while working on native code.

Koillection’s modular design, combined with its open‑source license and PWA support, gives developers a flexible platform that can be tailored to any collection type. Unlike monolithic services that lock you into proprietary metadata, Koillection lets you write your own scrapers or integrate with external APIs at will. Its Docker‑friendly deployment and automatic Swagger docs lower the barrier to entry, making it a compelling choice for teams that need full control over data ownership and extensibility.