lunch-notifier/CLAUDE.md

Lunch Notifier

Single-file Flask app that scrapes the Mariposa (Kyrene school district) lunch menu and pushes each day to a Home Assistant calendar as an all-day event. Runs as one Docker container on the user's Unraid home server.

2026-09-03: pivoted from SMS to calendar-only. Originally texted phone numbers via email-to-SMS carrier gateways; that whole path (Gmail SMTP, phone number management, carrier gateway settings) was deleted at the user's request in favor of Home Assistant calendar events exclusively. If you find references to texting/SMS/phone numbers anywhere (docs, old commits), they describe the pre-2026-09-03 app, not the current one.

2026-09-29: monthly → daily pulls, HA-side dedup. See "Pull scheduler" and "Home Assistant integration" below. Anything describing a day-25 monthly pull or "no dedup, re-pushing creates duplicates" describes the pre-2026-09-29 app.

2026-09-08: pivoted from Nutrislice to a Claude-read PDF, and from weekly to monthly pulls. The district discontinued Nutrislice (the old scraper hit kyrene.api.nutrislice.com, a clean per-day JSON API) in favor of publishing one monthly menu PDF per grade band on kyrene.org/family-student-resources/food-services/school-menus. See "Menu source" and "Daily pull scheduler" below for how that's handled now. Anything describing a weekly Nutrislice pull describes the pre-2026-09-08 app.

Architecture

• app.py — everything: Flask web UI/API, schedule-library job scheduling, and the Home Assistant webhook push. The HTML/CSS/JS frontend is embedded as a Python string constant (HTML) rather than a separate template file — no build step, no template engine.
• scraper.py — fetches the currently-published K-5 lunch menu PDF and asks Claude (Anthropic API, claude-opus-5, structured JSON output via output_config.format) to read it into [{"date": ..., "items": [...]}, ...] for every day of whatever month is published. Days with no posted menu (weekends, breaks, holidays) come back with an empty items list rather than being omitted — same contract the old Nutrislice-based scraper used, so app.py's push logic didn't need to change.
• Menu source (Nutrislice → PDF, 2026-09-08): the district's page links a stable Finalsite "resource manager" permalink (kyrene.org/fs/resource-manager/view/32bb3f8b-5a50-4b38-ad68-a5d3108de571 for the K-5/"Standard" menu — there's a different UUID per grade band/ campus on that page) that 302-redirects to whichever monthly PDF is currently live (scraper.MENU_PAGE_URL). Don't hardcode the PDF URL itself — it's a Finalsite CDN path that changes every month (verified: the September 2026 PDF and August's page both linked through the same permalink); only the permalink UUID is stable, and only changes if the district restructures that page entirely. The PDF itself is a single-page graphic calendar grid (mascots, colored cells, day numbers laid out visually) — not text-extractable in any reliable way (raw text extraction jumbles day numbers away from their menu items), which is why this reads it via Claude vision/document understanding rather than pdfplumber/ regex. Cost is negligible: one ~370KB single-page PDF per month, well under a cent of Opus 5 tokens.
• ANTHROPIC_API_KEY is now required (server .env, alongside HA_WEBHOOK_URL) — scraper.get_month_menu() fails without it, same fail-soft-into-_status-error behavior as a Home Assistant push failure. GET /api/integrations reports both keys' configured/not-configured state.
• Settings (just calendar_run_time) persist to /data/settings.json, not environment variables — the env var CALENDAR_RUN_TIME is a default used only before a settings file exists. _DEFAULTS is the complete schema: load_settings() merges the file over _DEFAULTS (so an old file missing a key still yields a valid schedule instead of zero jobs) and keeps only keys in _DEFAULTS; startup rewrites the file with that result. That pruning (2026-09-29) removed the SMS era's phone numbers / carrier gateway / vacations and the old calendar_run_day_of_month from the server's settings.json — they had lingered, unread, since the pivots.
• No vacation/no-push date ranges (removed 2026-09-03, briefly existed). A day with no posted menu already produces an empty items list from get_month_menu(), and _push_calendar() already skips pushing when items is empty — that's sufficient for "don't create an event for a day with nothing happening." A separate vacation-range setting to additionally suppress days the school did post a menu for was judged unnecessary complexity and deleted at the user's request; don't re-add it without being asked.
• Home Assistant integration (built 2026-09-02/03, calendar-only pivot 2026-09-03): HA_WEBHOOK_URL is required — it's the only way this app does anything externally-visible. On the HA side (automation.lunch_menu_family_calendar, http://192.168.86.207:8123), a local_only webhook trigger runs calendar.create_event against calendar.family_2 (the shared iCloud "Family" calendar, via CalDAV — there are two entities both named "Family" in this HA instance, calendar.family and calendar.family_2; this integration deliberately targets _2 per user choice). calendar.family_2 supports create_event and get_events but not delete_event — a bad push can't be cleaned up via the HA API, only by hand in the Calendar app. Automation mode history — queued since 2026-09-29. The app fires one webhook POST per school day back-to-back (HA answers each POST immediately, so the app never waits on the calendar write). single (default) dropped all but the first as failed_single (fixed 2026-09-03 → parallel); parallel then sent ~20 simultaneous CalDAV PUTs on a month push, overflowing iCloud (connection pool full + ~10× 500 Internal Server Error on the 2026-09-25 push). Now queued (max 40): one write at a time, nothing dropped. Dedup (2026-09-29): before creating, the automation reads the date with calendar.get_events and stops if a 🍱 Mariposa Lunch event already exists — that's what makes daily pulls safe. It verifies the event saved and retries once after 15s. Pre-dedup pushes left 2-3 copies on most early-September days; those have to be deleted by hand. The webhook id is a random token that lives only in the server's .env (HA_WEBHOOK_URL) and in the automation's trigger config — never committed here. If the calendar push stops working, check both ends: GET /api/integrations on this app reports whether HA_WEBHOOK_URL is set at all, and ha_get_automation_traces on automation.lunch_menu_family_calendar shows whether HA is even receiving the webhook.
• Daily pull scheduler (monthly → daily, 2026-09-29): push_month_to_calendar() runs every day at calendar_run_time (default 18:00; schedule job tagged "calendar" — schedule.clear("calendar"), not a bare schedule.clear(), so a future second schedule wouldn't stomp it). Why daily: the old once-a-month day-25 pull pushed whatever month was live at the permalink; when the district posted late (September 2026: the permalink still served September on 09-29), it silently re-pushed the current month and the next month's menu wouldn't be pulled until the following 25th — most of that month gone. Daily pulls pick up a new month the evening it's posted; HA-side dedup makes the repeats harmless, and the Claude read costs well under a cent a day. Each pull pushes only today onward (past dates are skipped — they're already on the calendar or no longer matter) and skips weekend dates that have items, logging a warning and noting it in the status result: there's never school lunch on a weekend, so that's a misread date (seen once: Fri 9/25's menu landed on Sat 9/26). Whatever month is live at the permalink is what gets read — there's no logic forcing "next month specifically."
• iPad dashboard reads /api/status (2026-09-29). The HA iPad wall dashboard's Ombi tab shows a lunch panel: today's menu (read from the HA calendar, not this app) plus pull time / next scheduled from /api/status. That page is served from HA (http://192.168.86.207:8123), a different origin, so _cors_for_dashboard adds Access-Control-Allow-Origin for that one origin on that one read-only endpoint. Changing /api/status's shape (next_calendar_run) breaks that panel; moving HA's address means updating DASHBOARD_ORIGIN.
• Manual actions: "Push This Month to Calendar" (POST /api/push-calendar → push_month_to_calendar(), same function the schedule calls — so it also pushes only today onward and skips weekend misreads) and "Preview This Month's Menu" (GET /api/preview → get_month_menu() directly, pure dry run, no Home Assistant push, no side effects at all — use this to check the scraper before trusting a scheduled push).

Local development

pip install -r requirements.txt
python3 app.py

Needs ANTHROPIC_API_KEY set for anything menu-related to work at all (including Preview, since that calls the same Claude-backed scraper) and HA_WEBHOOK_URL set to actually push anywhere — without the latter the app still runs and previews fine, GET /api/integrations just reports ha_webhook_configured: false and pushes resolve to "not configured". Visit http://localhost:2323.

Deployment

Target: Unraid server, container path /mnt/user/appdata/lunch-notifier, built from Dockerfile/docker-compose.yml in this repo. Container name Lunch-Notifier, port 2323. No reverse proxy — accessed directly via http://<server-ip>:2323 on the LAN.

Deploy mechanism: Forgejo push-to-deploy, same pattern as the other three projects on this box (card-grader, n64-tracker, arr-summary) — see card-grader's CLAUDE.md for the full pipeline mechanics (runner config, HTTPS-not-SSH git auth, known tradeoffs). In short: push to main on the forgejo remote (https://git.hippofam.com/ninja_hippo/lunch-notifier.git) triggers .forgejo/workflows/deploy.yml, which syncs into /mnt/user/appdata/lunch-notifier (excluding .git, .env, data/) and runs docker compose up -d --build. .env changes need an explicit docker compose up -d on the server afterward — env vars only load at container start, a deploy that doesn't change code won't pick up a manually-edited .env on its own.

Persistent state, never touched by deploys: data/settings.json (the volume-mounted /data inside the container) holds the calendar pull schedule — this is live user data, not deploy-managed. .env holds HA_WEBHOOK_URL and ANTHROPIC_API_KEY and is server-only, gitignored, never committed.

Container timezone (fixed 2026-09-08): the container previously had no timezone configured — python:3.12-slim defaults to UTC and the /etc/localtime bind mount in docker-compose.yml was commented out — so calendar_run_time (and the datetime.now() call in scraper.py that picks which week to fetch) were evaluated against UTC, not the user's local clock. This happened to be masked because Arizona (no DST) and Pacific Daylight Time are both UTC-7 right now, but would have silently drifted the actual fire time by an hour once PDT becomes PST in November. Fixed by uncommenting the /etc/localtime:/etc/localtime:ro bind mount and installing tzdata in the Dockerfile — without tzdata, the host's /etc/localtime (typically a symlink into /usr/share/zoneinfo/…) would dangle inside the container since that directory wouldn't exist, silently falling back to UTC again. Found while investigating why the first automatic Sunday calendar push after the 2026-09-03 pivot appeared not to run — that specific miss turned out to be unrelated (the school's Nutrislice menu was published empty for the whole week, so _push_calendar correctly skipped every day), but this latent TZ bug surfaced during the investigation and was worth fixing regardless.

Migration note (2026-08-25): this container originally used a Docker named volume (lunch-notifier_lunch-settings) instead of a bind mount. That meant Unraid's Appdata Backup plugin — which only knows about /mnt/user/appdata and /mnt/cache/appdata as backup sources — silently skipped it entirely; the settings data was never included in any backup. Migrated to a bind mount (./data:/data) with the existing settings copied over first and verified intact before the old named volume was deleted.