Specifically Clementines

Specifically Clementines is a lightweight, self‑hosted grocery and recipe management system that prioritizes real‑time synchronization across devices and users. At its core, the application exposes a RESTful API that allows clients to create, update, and delete shopping lists, items, and recipes while guaranteeing eventual consistency through a conflict‑resolution engine. The backend is written in Go, leveraging the net/http package and the popular gorilla/mux router for routing, while the persistence layer uses PostgreSQL with a JSONB column to store dynamic list schemas. A WebSocket endpoint (/ws) pushes delta updates to connected clients, enabling instant UI refreshes without polling.

Architecture

• Backend – Go (1.22+), gorilla/mux, go-pg ORM, PostgreSQL 15+. The service is split into modular packages: auth, lists, items, sync, and recipes. The sync package implements a CRDT‑style merge algorithm that automatically resolves concurrent edits, exposing a /sync/status endpoint for diagnostics.
• Frontend – A single‑page application built with SvelteKit. The client uses the native WebSocket API to listen for updates and falls back to IndexedDB for offline caching. The build is bundled by Vite, producing a static asset set that the Go server serves via an embedded http.FileServer.
• Deployment – The entire stack can run inside a single Docker container (docker-compose.yml includes services for API, frontend, and Postgres). For larger deployments, the API can be horizontally scaled behind a load balancer; PostgreSQL supports streaming replication for high availability.

Core Capabilities

• Multi‑user sharing – Lists and list groups can be shared with granular read/write permissions using JWT‑based authentication.
• Real‑time sync – WebSocket pushes guarantee that every client sees changes within milliseconds, even when the network drops and reconnects.
• Conflict resolution – The CRDT merge algorithm is deterministic; developers can hook into the onConflict event to customize resolution logic.
• Recipe integration – The /recipes/import/tandoor endpoint accepts a Tandoor recipe ID and expands it into list items, preserving quantity multipliers.
• Extensible APIs – All CRUD operations are exposed via REST; the API is documented with OpenAPI 3.0 and can be introspected by tools like Swagger UI or Postman.

Deployment & Infrastructure

The application is designed for self‑hosting with minimal operational overhead:

• A single Docker image contains the Go binary and static assets, making it trivial to run on any Linux host or cloud VM.
• The PostgreSQL instance can be backed up via pg_dump or restored with pg_restore; the schema is lightweight (≈20 kB).
• For scalability, deploy multiple API instances behind a reverse proxy (Traefik or Nginx) with sticky sessions to preserve WebSocket connections.
• The client is fully offline‑capable; IndexedDB stores pending mutations locally and synchronizes on reconnect, ensuring no data loss.

Integration & Extensibility

• Webhooks – The /webhook endpoint accepts POST payloads whenever a list or item changes, allowing integration with external services (e.g., Slack notifications).
• Plugin system – A simple Go plugin architecture lets developers load shared object files (*.so) that implement the SyncPlugin interface, enabling custom sync strategies or data transformations.
• Customization – Themes and UI components can be swapped by replacing the SvelteKit source; the build process supports environment variables for branding.

Developer Experience

• Documentation – The project hosts a comprehensive handbook (https://davideshay.github.io/groceries/) that covers API usage, deployment guides, and plugin development.
• Community – The repository has an active issue tracker; contributors can submit PRs for new features or bug fixes. Licensing is MIT, ensuring no restrictions on commercial use.
• Testing – Unit tests cover 85 % of the codebase; integration tests use Testcontainers to spin up a temporary PostgreSQL instance.

Use Cases

1. Family Shopping – Multiple family members add items from their phones; the shared list updates instantly on all devices.
2. Small Business Inventory – A boutique can track stock across multiple storefronts, with items auto‑checked once sold in any location.
3. Event Planning – Organizers create a list group for an event; vendors can update availability, and the master list resolves conflicts automatically.
4. Recipe‑Driven Meal Prep – Chefs import recipes from Tandoor, generating shopping lists that synchronize across kitchen devices.

Advantages

• Reliability – Built‑in CRDT sync eliminates the “freeze” issues common in other open‑source grocery apps.
• Performance – Go’s concurrency model keeps the API responsive under heavy write loads; WebSocket pushes avoid round‑trip latency.
• Flexibility – The plugin system and webhook support allow developers to extend functionality without touching the core code.
• Licensing – MIT license removes barriers for commercial deployment, unlike some alternatives that require paid subscriptions or proprietary backends.

Specifically Clementines offers a robust, developer‑friendly platform for anyone needing real‑time grocery list synchronization in a self‑hosted environment.