+
+
+
Your family's groceries and recipes in one private app you own, and that Claude can manage for you.
-License: [Elastic License 2.0](./LICENSE) — free for self-hosted personal / -internal use; cannot be offered as a managed third-party service. +- **Groceries and recipes** for the whole household, synced across everyone's phones +- **Installs like a native app** and keeps working offline (PWA) +- **Claude built in**: a secure MCP server lets you manage your lists and recipes by chat +- **Private by design**: runs on your own server, sign-in limited to your family +- **One login** for a growing set of small family apps (grocery and recipes today) -See the full architecture spec for context and rationale. +Under the hood: a single Bun process in one Docker image, deployed behind a +reverse proxy like Caddy. You own the deployment and the data. + +License: [Elastic License 2.0](./LICENSE). Free to self-host, use, modify, and +redistribute. You may not offer it to others as a hosted or managed service; +that requires a separate commercial license (contact us). --- ## Stack - **Runtime:** Bun (latest stable) -- **HTTP:** Hono v4 — serves API + MCP + static React in one process +- **HTTP:** Hono v4 (serves API + MCP + static React in one process) - **Frontend:** React 19 + Vite + TanStack (Router, Query, Form) + Tailwind v4 - **UI:** shadcn/ui (copy-paste, in `apps/web/src/components/ui/`) + Vaul (drawers) + Sonner (toasts) + Phosphor Icons - **DB:** `bun:sqlite` via Drizzle ORM (beta) -- **Auth:** Better Auth — Google sign-in (+ One Tap) for people; an OAuth 2.1 +- **Auth:** Better Auth, with Google sign-in (+ One Tap) for people; an OAuth 2.1 provider (`@better-auth/oauth-provider` + JWT) for MCP clients like Claude - **Validation:** Valibot at HTTP boundaries, Zod inside MCP tool defs only - **Tests:** `bun:test`; Playwright for end-to-end -- **Package manager:** pnpm 11 (hardened defaults — see `.npmrc` and +- **Package manager:** pnpm 11 (hardened defaults, see `.npmrc` and `pnpm-workspace.yaml`) ## Layout @@ -44,20 +49,21 @@ onehouse/ │ │ └── composition.test.ts # ← tests sit next to the code they cover │ └── web/ # React + Vite + PWA │ ├── src/{components,features,routes,lib}/ -│ └── e2e/ # Playwright — the only non-colocated tests -├── packages/ # Internal libraries — imported by apps and each other +│ └── e2e/ # Playwright, the only non-colocated tests +├── packages/ # Internal libraries, imported by apps and each other │ ├── core/ # Platform plumbing │ │ └── src/ │ │ ├── shared/ # Branded IDs, Result, isomorphic helpers (browser-safe) │ │ │ ├── ids.ts │ │ │ └── ids.test.ts │ │ └── server/ # Better Auth, db, MCP plumbing, middleware -│ └── app-grocery/ # First app — four subpaths enforce the boundary -│ └── src/ -│ ├── shared/ # State machines, Valibot, types (browser-safe) -│ ├── server/ # Drizzle schema, Hono routes, services -│ ├── tools/ # MCP tool definitions -│ └── ui/ # React components reused across entry points +│ ├── app-grocery/ # Grocery list; four subpaths enforce the boundary +│ │ └── src/ +│ │ ├── shared/ # State machines, Valibot, types (browser-safe) +│ │ ├── server/ # Drizzle schema, Hono routes, services +│ │ ├── tools/ # MCP tool definitions +│ │ └── ui/ # React components reused across entry points +│ └── app-recipes/ # Recipes; same four-subpath structure ├── drizzle/ # Generated migrations (committed) ├── data/ # SQLite + WAL (Docker volume) ├── scripts/ # migrate.ts, backup, etc. @@ -96,19 +102,19 @@ pnpm install # 2. Configure cp .env.example .env -# edit .env — see "Auth setup" below +# edit .env, see "Auth setup" below -# 3. Install git hooks (one-time; lefthook writes .git/hooks/* — `.npmrc` +# 3. Install git hooks (one-time; lefthook writes .git/hooks/*; `.npmrc` # has `ignore-scripts=true`, so this is NOT done automatically by install) pnpm hooks:install # 4. Run pending migrations (auth schema is committed, drizzle/0000_*.sql too) pnpm db:migrate -# 5. Dev (host) — server (3000) + Vite (5173) with hot reload +# 5. Dev (host): server (3000) + Vite (5173) with hot reload pnpm dev -# OR Dev (Docker) — bind-mounted hot reload +# OR Dev (Docker): bind-mounted hot reload docker compose --profile dev up ``` @@ -126,24 +132,24 @@ any user row is created. 2. Create an **OAuth 2.0 Client ID**, type **Web application** 3. Authorized JavaScript origins: - `http://localhost:5173` (local dev) - - `https://app.hejmly.com` (production) + - `https://