SPEC.md (3224B)
1 # Recipe & Grocery Bot — Project Spec 2 3 ## Overview 4 5 A Telegram bot, self-hosted on the homelab, for tracking recipes with 6 dietary tags (keto), maintaining a weekly staples list, and generating 7 merged grocery lists on demand. 8 9 ## Why Telegram over Slack 10 11 Telegram's Bot API supports long polling, so the bot can run entirely 12 inside the Tailscale network with no public-facing webhook, no reverse 13 proxy, and no OAuth app-review process. Slack bots generally want a public 14 HTTPS endpoint (or Socket Mode with more setup overhead) for the same 15 result. Telegram is the lower-friction choice for a single-user homelab 16 tool. 17 18 ## Setup Steps 19 20 1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram, get 21 the bot token. 22 2. Deploy target: new LXC or VM on Proxmox (or a lightweight container), 23 consistent with existing homelab conventions. 24 3. `pip install python-telegram-bot sqlite-utils python-dotenv` 25 4. Store the bot token in a `.env` file, excluded from version control. 26 5. Initialize the SQLite DB from `models.py` on first run (auto-create 27 tables if they don't exist). 28 6. Register a `systemd` unit for the bot process — restart on failure, 29 logs to journald (or wherever the rest of the stack logs to). 30 7. Optional: wire a Pushover notification into `notify.sh` for bot crashes 31 or DB errors, matching the existing pattern. 32 33 ## Data Model 34 35 See `CLAUDE.md` for full schema. Summary: 36 37 | Table | Purpose | 38 |---|---| 39 | `recipes` | Name, servings, instructions, source, dietary flags | 40 | `ingredients` | Per-recipe ingredient lines | 41 | `staples` | Recurring weekly items with default quantities | 42 | `grocery_list_items` | Current working list, tagged by source (staple/recipe/freeform) | 43 44 ## Command Reference 45 46 | Command | Behavior | 47 |---|---| 48 | `/addrecipe` | Add a new recipe, conversationally or by pasting text | 49 | `/recipes [tag]` | List recipes, optionally filtered by tag | 50 | `/staples` | View the weekly staples list | 51 | `/staples add <item>` | Add an item to staples | 52 | `/staples remove <item>` | Remove an item from staples | 53 | `/grocerylist [recipes...]` | Generate merged list: staples + named recipes | 54 | `/add <item>` | Freeform add to the current grocery list | 55 | `/clearlist` | Reset the working grocery list | 56 | `/random [tag]` | Suggest a random recipe, optionally filtered | 57 58 ## Dietary Safety Notes 59 60 Nut-free tracking was dropped as a requirement (single-user household, 61 user doesn't eat nuts, so nut recipes are unlikely to enter the system). 62 Keto tagging is auto-suggested and manually correctable. 63 64 ## Future Ideas (not in initial build) 65 66 - Web UI reading from the same SQLite DB 67 - Recipe URL parsing/import 68 - Grocery list grouped by store section 69 - Meal-planning calendar view 70 71 ## Handoff to Claude Code 72 73 Point Claude Code at this directory with both `CLAUDE.md` and `SPEC.md` 74 present. `CLAUDE.md` governs coding conventions and hard constraints; 75 `SPEC.md` is the human-readable reference. Suggested first prompt: 76 77 > Build the initial project structure per SPEC.md: SQLite schema, the 78 > `/addrecipe`, `/recipes`, `/staples`, `/grocerylist`, `/add`, and 79 > `/clearlist` commands, and a systemd unit file. Start with the DB layer 80 > and merge logic, then wire up the bot commands.