1 files changed, 54 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ab40482
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+A simple webapp for the family, regrouping tailor made tools (groceries,
+chores).
+
+## Architecture
+
+- SvelteKit (Svelte 5 runes) + adapter-node, no separate front/back
+- SQLite via **@libsql/client** + Drizzle ORM
+- Plain CSS (no framework), Vitest for tests, Prettier + ESLint flat config
+- Multi-stage Docker image (node:26-slim), served behind Caddy
+
+## Notable choices
+
+- **@libsql/client over better-sqlite3**: Node 26 removed V8 API surface
+  (`GetPrototype`, `This` on PropertyCallbackInfo) that better-sqlite3's
+  native addon depends on. @libsql/client is pure JS and works out of the
+  box.
+- **Plain CSS over Tailwind**: smaller dependency footprint, no build
+  step for styles.
+
+## Product
+
+### Groceries
+
+Two core concepts: the **catalog** (every item you've ever added) and the
+**list** (what to buy next). Adding an item puts it on the list; checking it
+off moves it back to the catalog. Items already on the list are marked as
+such in the catalog. Unchecked items stay on the list for the next shopping
+trip — there is only one persistent list.
+
+**Three modes of use:**
+
+1. **Quick add** — during the week, you run out of milk or need an ingredient.
+   Open the app, search, tap to add. As frictionless as possible so you
+   build the habit.
+
+2. **Planning** — before shopping, sit down with your partner and browse the
+   catalog. Re-add whatever you're missing. The catalog view stays open
+   after each add (sticky mode), so going through 20–30 items is not
+   frustrating. Stale one-off items can be deleted from the catalog.
+
+3. **Shopping** — items are grouped by category (matching store aisles).
+   Check off as you grab them. Multiple devices, same list — both partners
+   can check things off in sync.
+
+**Product references** — some items like "coffee" or "pasta" aren't generic.
+For these you can record one or more reference brands, each with a name,
+price per unit (€/kg or €/L), and a quality score (0–100). In the store, if
+you're unsure which brand you usually buy or you spot an alternative, you
+can compare against your references right from the item. If a new brand
+wins, you can add it or switch the reference.
+
+**Categories** — items are auto-categorized (LLM-assisted) and can be
+manually adjusted. Categories correspond to physical store aisles for an
+efficient shopping walk.