2. Architecture Constraints

2.1 Technical Constraints

Constraint	Description	Rationale
PWA only	One web UI delivered as a PWA; no native shell	Single codebase, easy updates (ADR-039)
Mobile-first	UI designed for phones, responsive up to desktop	Main use is kitchen and grocery shopping
Client stack	React 19, Vite, IndexedDB via PouchDB (Section 4.2)	Offline-first persistence, CouchDB-compatible replication
Bun	Bun for installs and scripts; never npm, yarn or pnpm	Fast installs, runs TypeScript directly
Internationalization	German and English from the start; strings in `src/locales/`	Learnability for the primary audience
Deployment-selected sync mode	`/forked-config.json` (`gatewayUrl`, `couchdbUrl`) selects self-hosted or forked cloud mode	Users never choose; one image serves both (ADR-038)
Direct replication	The PWA replicates directly with CouchDB; no backend in the data path	One sync path (ADR-028)
Self-hosted auth	Basic auth against the fixed database `forked`	Login-only flow; cookie-based proxy or SSO auth is outside the flow
Gateway outside the repository	The operator’s gateway and website are not in this repository	Only the client contract is public (Section 7.3)
Layering	`app` > `features` > `shared` > `infrastructure` > `core`, downward only, no cycles	Enforced by an architecture test (ADR-031)

Constraint	Description	Impact
Agent-driven development	Primary development by coding agents with human review	Docs are the primary context and must be explicit and current
Maintainer-owned decisions	One maintainer decides architecture	Agents present options before architectural changes (Section 8.9)
Non-profit, open source (MIT)	No funding except optional hosting; MIT-compatible dependencies only	Free and open-source tools, minimal operating cost

Coding standards: .claude/rules/. Working rules and validation commands for agents: CLAUDE.md.
Commits follow Conventional Commits: <type>(<scope>): <subject>, scopes frontend, docs, arc42, agents, deps; ! after the type marks a breaking change.