# mrbill700/weekly-meal-plan architecture

> Architecture diagram of the GitHub repository mrbill700/weekly-meal-plan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrbill700/weekly-meal-plan
- Repository: https://github.com/mrbill700/weekly-meal-plan

## Overview

This repository is a scheduled weekly dinner-planning emailer, with an optional podcast publisher. The main workflow gathers and filters recipes from configured blogs, samples them for the week, uses an AI model plus household rules and meal history to create a plan and grocery list, emails the result, and records meals for future rotation and ratings. The podcast turns recorded meals into spoken episodes for a separate public site. The main implementation is concentrated in two Python files; finer internal divisions reflect documented capabilities, not separate modules. Several links are supported by the README because implementation excerpts are incomplete.

Main entry points: [`meal_planner.py`](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py) (Planner runtime), [`podcast.py`](https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py) (Podcast publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Meal planning"]
  node_planner["Planner runtime<br/>[meal_planner.py]"]
  node_catalog[("Recipe catalog<br/>[meal_planner.py]")]
  node_recipe_filter["Dinner filtering<br/>[meal_planner.py]"]
  node_weekly_sample["Weekly sample<br/>[meal_planner.py]"]
  node_history_read[("History and ratings<br/>[meal_planner.py]")]
  node_ai_plan["Plan generation<br/>[meal_planner.py]"]
  node_groceries["Store grocery list<br/>[meal_planner.py]"]
end

subgraph group_delivery["Email and history"]
  node_email_render["Email rendering<br/>[meal_planner.py]"]
  node_history_write[("Meal history<br/>[meal_planner.py]")]
end

subgraph group_podcast["Podcast publishing"]
  node_podcast_runtime["Podcast publisher<br/>[podcast.py]"]
  node_episode_script["Episode script<br/>[podcast.py]"]
  node_voice_audio["Voice and audio<br/>[podcast.py]"]
end

node_household(("Household"))
node_blogs(("Recipe blogs"))
node_gmail["Gmail SMTP"]
node_primary_ai["Claude API"]
node_fallback_ai["OpenRouter API"]
node_podcast_site["Public podcast site"]
node_listener(("Podcast listener"))

node_household -->|"configures"| node_planner
node_planner -->|"fetches sitemaps"| node_blogs
node_planner -->|"builds catalog"| node_catalog
node_planner -->|"filters recipes"| node_recipe_filter
node_planner -->|"samples recipes"| node_weekly_sample
node_planner -->|"loads history"| node_history_read
node_planner -->|"generates plan"| node_ai_plan
node_ai_plan -->|"requests plan"| node_primary_ai
node_ai_plan -.->|"retries on error"| node_fallback_ai
node_planner -->|"builds list"| node_groceries
node_planner -->|"renders email"| node_email_render
node_email_render -->|"sends email"| node_gmail
node_planner -->|"records meals"| node_history_write
node_history_write -->|"feeds rotation"| node_history_read
node_history_write -->|"provides latest meals"| node_podcast_runtime
node_podcast_runtime -->|"writes script"| node_episode_script
node_episode_script -.->|"requests script"| node_primary_ai
node_episode_script -.->|"tries fallback"| node_fallback_ai
node_podcast_runtime -->|"generates audio"| node_voice_audio
node_voice_audio -->|"publishes episode"| node_podcast_site
node_podcast_site -->|"serves feed"| node_listener

click node_planner "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_catalog "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_recipe_filter "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_weekly_sample "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_history_read "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_ai_plan "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_groceries "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_email_render "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_history_write "https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py"
click node_podcast_runtime "https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py"
click node_episode_script "https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py"
click node_voice_audio "https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_planner,node_catalog,node_recipe_filter,node_weekly_sample,node_history_read,node_ai_plan,node_groceries toneBlue
class node_email_render,node_history_write toneAmber
class node_podcast_runtime,node_episode_script,node_voice_audio,node_primary_ai,node_fallback_ai toneMint
class node_household,node_blogs,node_gmail,node_podcast_site,node_listener toneIndigo
```

## Components

### Meal planning

- [Planner runtime](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Recipe catalog](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Dinner filtering](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Weekly sample](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [History and ratings](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Plan generation](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Store grocery list](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`

### Email and history

- [Email rendering](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`
- [Meal history](https://github.com/mrbill700/weekly-meal-plan/blob/main/meal_planner.py): `meal_planner.py`

### Podcast publishing

- [Podcast publisher](https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py): `podcast.py`
- [Episode script](https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py): `podcast.py`
- [Voice and audio](https://github.com/mrbill700/weekly-meal-plan/blob/main/podcast.py): `podcast.py`

### Other components

- **Household**
- **Recipe blogs**
- **Gmail SMTP**
- **Claude API**
- **OpenRouter API**
- **Public podcast site**
- **Podcast listener**

## Connections

- Household → Planner runtime: configures (evidence: `README.md`)
- Planner runtime → Recipe blogs: fetches sitemaps (evidence: `README.md`)
- Planner runtime → Recipe catalog: builds catalog (evidence: `README.md`)
- Planner runtime → Dinner filtering: filters recipes (evidence: `README.md`)
- Planner runtime → Weekly sample: samples recipes (evidence: `README.md`)
- Planner runtime → History and ratings: loads history (evidence: `meal_planner.py`)
- Planner runtime → Plan generation: generates plan (evidence: `meal_planner.py`)
- Plan generation → Claude API: requests plan (evidence: `README.md`)
- Plan generation → OpenRouter API: retries on error (evidence: `README.md`)
- Planner runtime → Store grocery list: builds list (evidence: `README.md`)
- Planner runtime → Email rendering: renders email (evidence: `README.md`)
- Email rendering → Gmail SMTP: sends email (evidence: `README.md`)
- Planner runtime → Meal history: records meals (evidence: `README.md`)
- Meal history → History and ratings: feeds rotation (evidence: `README.md`)
- Meal history → Podcast publisher: provides latest meals (evidence: `podcast.py`)
- Podcast publisher → Episode script: writes script (evidence: `podcast.py`)
- Episode script → Claude API: requests script (evidence: `podcast.py`)
- Episode script → OpenRouter API: tries fallback (evidence: `podcast.py`)
- Podcast publisher → Voice and audio: generates audio (evidence: `podcast.py`)
- Voice and audio → Public podcast site: publishes episode (evidence: `podcast.py`)
- Public podcast site → Podcast listener: serves feed
