MealQuest/docs/ARCHITECTURE.md

# MealQuest architecture

This mirrors the architecture section of `CONTEXT.MD` in the CTXD project
`mealquest`, which is the source of record; if the two disagree, CTXD wins and
this file should be updated. It describes the **planned** application. The
repository today is the Feature 01 scaffold: `cmd/server`, `internal/config`,
`internal/server` (`/health`), `internal/frontend` (embedded PWA with SPA
fallback), the `web/` skeleton, `Makefile`, `Dockerfile` and CI.

Decision numbers (D-NNN) refer to `DECISIONS.MD` in CTXD.

## Topology

```
PWA (phone / tablet / desktop)
   │ HTTPS
   ▼
Traefik v3.6 — 10.60.1.33
   file route: mealquest-ccl.yml
   │
   ▼
docker compose project "mealquest" — 10.60.1.14
   ├── mealquest   Go service + embedded PWA, port 8090
   ├── searxng     sidecar for recipe search
   └── Litestream  SQLite replication → Synology NAS 10.60.1.50
```

One container serves the API, the auth flow, media and the PWA. SQLite lives
on the host volume and is continuously replicated by Litestream to the NAS.

## Repository layout

| Path | Purpose |
| --- | --- |
| `cmd/server` | Entry point; wiring only. |
| `internal/config` | Env-only `MEALQUEST_*` config; secrets from `*_FILE`. |
| `internal/server` | HTTP server, router, middleware. |
| `internal/frontend` | Embedded PWA, SPA fallback. |
| `internal/auth` | Authentik OIDC, sessions, CSRF. |
| `internal/db`, `internal/store` | SQLite connections, sqlc queries. |
| `internal/secretbox` | AES-256-GCM encryption for `_ct` columns. |
| `internal/household`, `internal/dinners`, `internal/recipes` | Domain. |
| `internal/ai/llm`, `internal/ai/harness`, `internal/ai/skills` | AI provider adapters, skill harness, skills. |
| `internal/suggest`, `internal/plan`, `internal/shopping`, `internal/ideas` | Feature services. |
| `internal/gcal`, `internal/notify`, `internal/push`, `internal/chat` | Integrations. |
| `internal/jobs`, `internal/scheduler` | Background jobs and schedules. |
| `migrations/` | SQL migrations (embedded; no goose/golang-migrate). |
| `web/` | React PWA. |
| `deploy/` | Compose, Traefik route, Litestream config. |
| `docs/` | Documentation. |
| `design/` | Requirements and UI handoff (read-only reference). |

## Backend stack and conventions

- Go 1.25, `CGO_ENABLED=0`, a single static binary.
- Router: `go-chi/chi/v5`. Logging: `log/slog` (structured).
- SQLite via `modernc.org/sqlite`, with `journal_mode=WAL`,
  `foreign_keys=ON` and `busy_timeout`. **One writer connection plus a read
  pool.** Queries generated by `sqlc`.
- IDs are ULIDs (`oklog/ulid/v2`).
- Timestamps are stored in UTC; local calendar dates are `YYYY-MM-DD` strings
  in the household timezone.
- Configuration is environment-only (`MEALQUEST_*`). Secrets come only from
  files named by `*_FILE` variables. Missing or invalid config stops startup.
- Error responses always have the body
  `{"error":{"code":"…","message":"…","retryable":false}}`.

## Authentication

- Authentik OIDC; the backend is a **confidential client** (authorization
  code flow handled server-side with `coreos/go-oidc/v3` and `x/oauth2`).
- Session cookie `__Host-mealquest_session` (Secure, HttpOnly, path `/`).
- Unsafe requests require the CSRF header `X-MealQuest-CSRF`.
- Access requires membership of the Authentik group `mealquest-admin`.
  There is a **single role**: one shared household, no per-person profiles.

## Data model

Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).

| Table | Holds |
| --- | --- |
| `household_settings` | Household name, timezone, preferences. |
| `recipes` | Dinners: name, method, minutes, difficulty, source, lifecycle status. |
| `recipe_ingredients` | Ingredients with quantities per recipe. |
| `recipe_steps` | Ordered steps per recipe. |
| `photos` | Cached recipe photos. |
| `dinners` | Dinner records and lifecycle state. |
| `suggestion_batches` | One AI suggestion run. |
| `suggestions` | Side quests with reason ("Why this?") and Try it / Pass status. |
| `week_plans` | One plan per Monday-start week; draft or synced. |
| `plan_days` | The dinner for each day of a week plan. |
| `rotation_reviews` | Rotation check answers ("Keep it in rotation?"). |
| `shopping_lists` | One Supply run per week; frozen into the Supply archive after the week. |
| `shopping_groups` | Items grouped by dinner. |
| `shopping_items` | Items, quantity, needed / have-it. |
| `ai_settings` | Provider, model, temperature, system prompt, API key (`_ct`). |
| `recipe_search_settings` | Recipe search configuration (searxng). |
| `integrations_google` | Google Calendar OAuth tokens (`_ct`) and calendar id. |
| `chat_settings` | Google Chat webhook URL (`_ct`). |
| `notification_prefs` | Per-event push / Chat toggles, reminder time. |
| `push_subscriptions` | Web Push subscriptions. |
| `notification_outbox` | Pending notifications for delivery. |
| `jobs` | Durable background job queue. |
| `schedule_runs` | Record of scheduled runs (idempotency). |
| `ai_runs` | Every AI skill call: inputs, outputs, validation, timing. |
| `sessions` | Server-side sessions. |

## Dinner lifecycle

```
suggested ──Try it──▶ quest_log ──cooked──▶ tried ──Rotation check──▶ regular
    │                                          └────────────────────▶ archived
    └──Pass──▶ declined (not suggested again)
```

Promotion to Regular is **never automatic** (D-021): it happens only when the
household answers "Keep it in rotation?".

## API surface

- JSON API under `/api/v1`, using the error body above for every failure.
- `/auth/*` — OIDC login, callback, logout.
- `/media/*` — cached photos.
- `/health` — liveness.
- Everything else serves the embedded PWA with SPA fallback.

## AI layer

- **Provider interface** (`ai/llm`) with adapters for OpenAI-compatible,
  Anthropic and Ollama endpoints, called over plain HTTP — no vendor SDKs.
- **Skill harness** (`ai/harness`): each skill (suggestions, week draft,
  ingredient ideas, quick ideas, archive post titles, …) layers its prompt —
  system prompt from `ai_settings`, skill instructions, household context —
  then validates the structured output against the skill's schema. An invalid
  response gets **one repair retry**; a second failure is an error, never a
  silent fallback. Every call is recorded in `ai_runs`.

## Recipe grounding

- Recipes are grounded in real pages found via the `searxng` sidecar.
- Fetching is **SSRF-safe** (public addresses only, size and time limits).
- Recipe data is parsed from schema.org `Recipe` JSON-LD.
- Photos are downloaded, processed (`golang.org/x/image`) and cached locally;
  the client never hot-links external images.

## Scheduler

Times are in the household timezone.

| Schedule | When | Does |
| --- | --- | --- |
| `suggestions_weekly` | Sunday 08:00 | New batch of Side quests. |
| `plan_draft` | Friday 09:00 | AI drafts next week's plan. |
| `shopping_chat_autosend` | Saturday 08:00 | Sends the Supply run to Google Chat. |
| `day_of_reminder` | Daily 16:30 | Tonight's dinner reminder. |
| `rotation_check` | Daily 09:00 | Asks "Keep it in rotation?" for tried dinners. |
| `week_rollover` | Monday 00:05 | Freezes last week's list into the Supply archive, rolls the plan. |
| `ai_runs` purge | Periodic | Deletes old `ai_runs` rows. |

Runs are recorded in `schedule_runs` and executed through `jobs`.

## Notifications

- Events: plan ready, list ready, day-of reminder, new suggestions; each can
  go to Web Push and/or Google Chat per `notification_prefs`.
- Delivery goes through `notification_outbox`.
- Web Push uses VAPID (`webpush-go`). Google Chat uses the stored incoming
  webhook.

## Google Calendar

- One-way push: the app is the source of truth; edits in Google Calendar do
  not come back.
- OAuth once in Settings; one event per planned dinner.
- **Deterministic event ids** derived from the plan day, so re-pushing
  updates the same events instead of creating duplicates.

## Frontend

- React 19, TypeScript, Vite, React Router 7, TanStack Query 5,
  `vite-plugin-pwa`, `lucide-react` (stroke 2.75).
- CSS Modules over `tokens.css`; no Tailwind, no Framer Motion, no
  hard-coded hex. Self-hosted Bagel Fat One and Figtree.
- Tests: Vitest, Testing Library, jsdom.
- Offline cache for the current plan, shopping list and recipes.

| Route | Screen |
| --- | --- |
| `/` | Home |
| `/onboarding` | Add Regulars |
| `/plan` | Weekly plan (Draft board) |
| `/plan/shopping` | Supply run |
| `/plan/shopping/archive` | Supply archive |
| `/discover` | Swipe Side quests |
| `/quick` | Quick dinners |
| `/cook-from-pantry` | Cook from what I have |
| `/dinner/:id` | Recipe detail / Kitchen reading mode |
| `/settings` | Settings home |
| `/settings/notifications` | Notifications and Google Chat |
| `/settings/ai` | Admin · AI assistant |

## Boundaries and gotchas

- **Secrets never reach the client** — API keys, OAuth tokens and the Chat
  webhook stay server-side, encrypted at rest.
- **The app is the source of truth for the plan**; Google Calendar is a
  one-way mirror.
- **Never auto-promote to Regular** (D-021).
- **Quick** means cooked in a crock pot **or** ≤ 30 minutes prep to table.
- **Weeks run Monday–Sunday** in the household timezone.
- **No silent fallbacks** — fail fast and report.
- **iOS Web Push requires the PWA to be installed to the Home Screen**; show
  an install hint.