KitchenOwl

KitchenOwl is a fully self‑hosted, cross‑platform recipe and grocery list manager that exposes a RESTful API for programmatic access. From a developer’s perspective, the application is built as a modular monolith with a clear separation between the backend service and the frontend clients (Web, Android, iOS, Desktop). The backend is a Spring Boot application written in Java 21, leveraging the Spring Data JPA layer to persist data into a relational database (PostgreSQL by default). The API follows standard HTTP semantics, supports JSON payloads, and includes authentication via JWT tokens with optional OAuth2 integration for single‑sign‑on scenarios.

Architecture

• Backend: Spring Boot (Java 21) + Spring Security, Spring Data JPA, Flyway for schema migrations.
• Database: PostgreSQL (recommended), with optional support for MariaDB/MySQL via JDBC.
• Frontend: A single‑page application built with Vue.js 3 and TypeScript, compiled to a static bundle that can be served by the same Spring Boot application or via an external CDN.
• Containerization: Official Docker images are available on Docker Hub (tombursch/kitchenowl). The container exposes a single port (8080) and mounts a volume for the database data directory.
• Real‑time sync: WebSocket support is implemented via Spring’s STOMP over SockJS, enabling instant updates to shopping lists and recipe collections across multiple clients.
• Offline support: The mobile apps use a local SQLite cache and background sync workers to queue changes while offline, then reconcile on reconnect.

Core Capabilities

• CRUD for recipes, grocery items, shopping lists, meal plans, and expense tracking via a well‑documented REST API.
• Webhooks: Clients can register endpoints to receive POST notifications on events such as item_added, recipe_shared, or expense_updated.
• Import/Export: Supports JSON and CSV formats for bulk recipe imports and shopping list exports.
• User management: Role‑based access control (admin, user) with support for group sharing of recipes and lists.
• Search & filtering: Full‑text search on recipe titles, ingredients, and tags; query parameters allow pagination and sorting.

Deployment & Infrastructure

KitchenOwl is designed for docker‑native deployment but can also be installed via traditional package managers (e.g., apt, Homebrew). The application requires:

• Java 21 runtime or a Docker image.
• PostgreSQL (or any JDBC‑compatible RDBMS).
• Optional Redis for caching and session storage.
• Persistent volumes for database data and optional configuration overrides.

The project includes a docker-compose.yml template that sets up the backend, database, and a reverse‑proxy (Traefik) with automatic HTTPS via Let’s Encrypt. For high‑availability, the Spring Boot service can be scaled horizontally behind a load balancer; the WebSocket implementation supports sticky sessions or uses Redis as a message broker.

Integration & Extensibility

• Plugin system: While currently minimal, the architecture exposes a service registry that can be extended with custom Spring beans.
• Home Assistant integration: A dedicated HACS repository (kitchenowl-ha) allows Home Assistant to consume KitchenOwl data, demonstrating the API’s ease of consumption.
• Custom UI: The Vue.js frontend is open‑source; developers can fork and modify the SPA or replace it entirely with a custom client that consumes the same API.
• SDKs: No official SDKs yet, but the clear REST contract and OpenAPI spec (auto‑generated) enable quick generation of client libraries in any language.

Developer Experience

The project places a strong emphasis on documentation: the public docs portal (docs.kitchenowl.org) includes a self‑hosting guide, API reference, and developer FAQ. The source code follows standard Java conventions, with comprehensive unit tests (JUnit 5) and integration tests that run against an embedded PostgreSQL instance. The community is active on Matrix (#kitchenowl:matrix.org) and GitHub, facilitating rapid issue triage and feature discussions. Licensing under AGPL‑3.0 ensures that any modifications remain open, encouraging collaboration.

Use Cases

• Home automation: Integrate KitchenOwl with smart fridges or kitchen displays via the REST API to auto‑populate shopping lists.
• Meal‑planning services: Build a subscription service that recommends recipes based on pantry inventory and sends push notifications to users.
• Enterprise kitchen management: Deploy in a corporate cafeteria setting, using the expense tracking to monitor food budgets.
• Open‑source kitchen projects: Fork KitchenOwl to create a localized, privacy‑first recipe hub for educational institutions or community centers.

Advantages

• Full control: Self‑hosting guarantees data privacy and eliminates reliance on third‑party cloud services.
• Performance: Spring Boot’s embedded server and JPA optimizations deliver low latency for CRUD operations; WebSocket sync keeps UI state consistent.
• Extensibility: The combination of a well‑defined REST API, Webhooks, and an open‑source frontend makes it straightforward to add new features or integrate with existing ecosystems.
• Community & Licensing: AGPL‑3.0 encourages open contributions, while the active community ensures rapid bug fixes and feature rollouts.

In summary, KitchenOwl offers a robust, developer‑friendly foundation for building or extending