1. Introduction and Goals
1.1 Requirements Overview
forked is an open-source (MIT), privacy-first recipe manager with a shopping list. It works offline and syncs optionally. Existing recipe managers tend to lock users into proprietary ecosystems, need connectivity, monetize data, and lack private household sharing.
| Capability | Requirement |
|---|---|
| Recipes | Create, edit, organize, search, plan; import from JSON files and photos; export to Schema.org and a lossless backup |
| Shopping list | Add recipe ingredients with amounts; categories group items by aisle |
| Offline-first | All of the above works without a network |
| Optional sync | Keep devices in sync. The deployment picks the mode: your own CouchDB with a login (self-hosted), or forked cloud with an account (Section 4.4) |
| Privacy | Local storage first; AI import only with explicit consent; no tracking |
| Languages | German and English, extendable |
Target audience: home cooks, families sharing a household, privacy-conscious users, and contributors extending the open-source system.
The project is non-profit. An optional paid forked cloud is run by an operator outside this repository.
1.2 Quality Goals
| Priority | Quality goal | Key requirements |
|---|---|---|
| 1 | Usability | Intuitive mobile-first UI for kitchen and shopping tasks |
| 2 | Learnability | Quick to understand, minimal configuration |
| 3 | Offline-First | Full functionality without connectivity |
| 4 | Privacy | User-controlled data, local-first storage, secure handling of credentials and egress |
| 5 | Internationalization | German and English, expandable |
Secondary goals: Performance (fast search with 1000+ recipes), Reliability (convergent sync), Operability (env-driven Docker deployment for self-hosters), Evolvability (an operator can offer accounts without changing the client). Concrete scenarios are in Section 10.
1.3 Stakeholders
| Role | Expectation | Where it shapes the architecture |
|---|---|---|
| End user | Easy recipe management, offline access, privacy | Offline-first, mobile-first UI |
| Family | Shared household collection across devices | Shared-database sync, conflict convergence |
| Self-hoster | Simple bootstrap, HTTPS, understandable recovery | Docker stack, login-only sync (Section 7.1) |
| Operator | Run forked cloud: accounts, device approval, sync tokens | Gateway outside the repository; the PWA fixes only the client contract (Section 7.3) |
| Maintainer | Sustainable complexity, clear decisions | Owns requirements and architecture decisions, reviews output |
| Coding agent | Complete, unambiguous context | These docs and CLAUDE.md are the primary interface; code and docs change together (Section 8.9) |
| Contributor | Transparent contribution process | Pull requests welcome |