3. System Context and Scope
3.1 Business Context
| Entity | Interface | Data flow | Purpose |
|---|---|---|---|
| User | Web UI in a browser or the installed PWA | Bidirectional | Recipes, shopping lists, settings |
| Files | Upload and download | Import and export | Recipe JSON import, Schema.org zip export, forked backup (Section 8.6) |
| Camera and photos | Device camera and gallery | Input only | Photo import of printed recipes; scanning pairing QR codes (cloud mode) |
| AI provider (optional) | HTTPS, user’s own API key | Content out | Photo import; opt-in per provider (ADR-024) |
| Own CouchDB (optional) | HTTPS, CouchDB replication, Basic auth | Bidirectional sync | Self-hosted mode: household data across devices |
| Operator gateway (optional) | HTTPS API announced by /forked-config.json | Enrollment, tokens | Cloud mode: device approval, invites, sync tokens; not in this repository (ADR-038) |
| Operator website (optional) | System browser, opened by the PWA | Links only | Cloud mode: sign-in, approval page, account management |
3.2 Technical Context
graph TB
subgraph "Household device"
PWA["Forked PWA"]
LocalDB[("PouchDB / IndexedDB")]
end
subgraph "Own sync infrastructure (self-hosting)"
Proxy["Reverse proxy<br/>allowlist, rate limit"]
Couch[("CouchDB")]
end
subgraph "Operator (optional, outside this repository)"
Gateway["Gateway<br/>approval, enrollment, tokens"]
Website["Website<br/>sign-in, approval page, account"]
OpCouch[("Operator CouchDB")]
end
AI["AI provider (opt-in)"]
PWA -->|Read and write| LocalDB
PWA -->|"Self-hosted: replication, Basic auth"| Proxy
Proxy --> Couch
PWA -.->|"Cloud: approval, invites, session"| Gateway
PWA -.->|"Cloud: opens pages in system browser"| Website
PWA -->|"Cloud: replication, short-lived JWT"| OpCouch
Gateway -.->|Provisioning only| OpCouch
PWA -.->|"Photo import, user's key"| AI
style PWA fill:#DBEAFE,stroke:#1F2937,color:#111827
style LocalDB fill:#FEF3C7,stroke:#1F2937,color:#111827
style Proxy fill:#DCFCE7,stroke:#1F2937,color:#111827
style Gateway fill:#DCFCE7,stroke:#1F2937,color:#111827
style Website fill:#DCFCE7,stroke:#1F2937,color:#111827
style Couch fill:#FCE7F3,stroke:#1F2937,color:#111827
style OpCouch fill:#FCE7F3,stroke:#1F2937,color:#111827
style AI fill:#F3F4F6,stroke:#1F2937,color:#111827
Interfaces:
| Interface | Contract |
|---|---|
| CouchDB replication | The only sync path, both modes (ADR-028). Basic auth in self-hosted mode, Bearer JWT in cloud mode. Behavior: Section 6. |
| Runtime announcement | GET /forked-config.json returns {"gatewayUrl", "couchdbUrl"} and selects the sync mode (Section 7.2). |
| Operator gateway | Session, device approval, invite, accept-invite, disconnect and sync-token routes (Section 7.3). |
| Browser APIs | IndexedDB, service worker, file, camera (getUserMedia, BarcodeDetector). |
3.3 Scope
Inside: the PWA (recipes, shopping list, settings, search, localization), local persistence, the sync client for both modes including the gateway client, import and export, and the self-hosting deployment files.
Outside:
- The operator’s gateway and website; self-hosters bring a plain CouchDB.
- AI providers, which are used only for opt-in photo import with the user’s own key.
- Recipe websites, external backup providers, grocery or commerce integrations, nutrition engines, smart kitchen devices.
3.4 Data Placement
- Device (primary): recipes, shopping lists and settings in the local PouchDB store. Core behavior needs no server.
- Sync store (optional): a CouchDB the user or an operator controls, one database per household. It exists only when sync is configured.
- Operator gateway (cloud mode only): device approval, enrollment and token issuance. Account data (email address) stays with the operator. It never carries replication traffic.
Users own what they create or import. Export works without any hosted service, and local-only use is a first-class mode. Security and privacy rules: Section 8.3.