If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mealie-recipes/mealie shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 16 active contributors
• Distributed ownership (top contributor 46% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mealie-recipes/mealie repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mealie-recipes/mealie.

What it runs against: a local clone of mealie-recipes/mealie — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mealie-recipes/mealie | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch mealie-next exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mealie-recipes/mealie. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mealie-recipes/mealie.git
#   cd mealie
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mealie-recipes/mealie and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mealie-recipes/mealie(\\.git)?\\b" \\
  && ok "origin remote is mealie-recipes/mealie" \\
  || miss "origin remote is not mealie-recipes/mealie (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify mealie-next >/dev/null 2>&1 \\
  && ok "default branch mealie-next exists" \\
  || miss "default branch mealie-next no longer exists"

# 4. Critical files exist
test -f "docker/docker-compose.yml" \\
  && ok "docker/docker-compose.yml" \\
  || miss "missing critical file: docker/docker-compose.yml"
test -f ".github/workflows/pull-requests.yml" \\
  && ok ".github/workflows/pull-requests.yml" \\
  || miss "missing critical file: .github/workflows/pull-requests.yml"
test -f "dev/code-generation/main.py" \\
  && ok "dev/code-generation/main.py" \\
  || miss "missing critical file: dev/code-generation/main.py"
test -f ".github/copilot-instructions.md" \\
  && ok ".github/copilot-instructions.md" \\
  || miss "missing critical file: .github/copilot-instructions.md"
test -f "Taskfile.yml" \\
  && ok "Taskfile.yml" \\
  || miss "missing critical file: Taskfile.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mealie-recipes/mealie"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Mealie is a self-hosted recipe manager and meal planner with a Python/FastAPI backend and Vue.js/TypeScript frontend that automatically scrapes recipe data from URLs or lets users manually input recipes into a queryable database. It provides REST APIs for recipe imports, meal planning, shopping list generation organized by store sections, and cookbook management—deployed via Docker with 35+ language localizations. Monolithic full-stack structure: Python backend (FastAPI) in the root mealie/ directory with schema generation (dev/code-generation/gen_py_schema_exports.py), frontend Vue/TypeScript app sharing schema types (dev/code-generation/gen_ts_types.py), Docker setup via Dockerfile and devcontainer, CI/CD orchestrated through GitHub Actions workflows, and translations coordinated via Crowdin (crowdin.yml).

Home cooks and families who want to self-host their recipe collection without relying on cloud services; developers building integrations via the REST API; contributors working in Python backend services or Vue/TypeScript frontend features.

Production-ready and actively maintained. The project has strong community signals (Discord, 35+ language translations, comprehensive CI/CD pipelines in .github/workflows/), demonstrated by test suites (test-backend.yml, test-frontend.yml, e2e.yml), regular Docker releases, and semantic versioning via release-drafter.yml. Recent workflow files and devcontainer setup indicate active ongoing development.

Low-to-moderate risk for a self-hosted application. Dependencies are substantial (2M+ Python, 880K+ Vue lines) requiring diligent updates; the monolith architecture means frontend and backend changes are tightly coupled. No single-maintainer risk visible (MAINTAINERS.md exists), but recipe scraper failures are common (dedicated bug report template suggests this is a known pain point). Breaking API changes possible across versions given active development.

Active development across multiple workstreams: automated dependency updates (auto-merge-dependencies.yml), localization syncing (locale-sync.yml, crowdin.yml), nightly test runs, container scanning (partial-trivy-container-scanning.yml), and pull request automation. The presence of release-drafter.yml and scheduled-checks.yml suggests coordinated versioning and regression prevention.

Clone and use dev containers: git clone https://github.com/mealie-recipes/mealie.git && cd mealie. Open in VSCode with devcontainer extension (see .devcontainer/devcontainer.json for Docker-based environment). Alternatively, examine Taskfile.yml for task-based setup: task --list to see available development tasks.

Daily commands: Check Taskfile.yml for task definitions: task dev likely spins dev server. Use devcontainer: reopen repo in container via VSCode (F1 > 'Reopen in Container'). Docker Compose may be used (implied by .dockerignore); inspect .devcontainer/Dockerfile for build steps. Frontend likely runs on localhost:3000 or 5173 (Vite default), backend on localhost:8000 (FastAPI default).

• docker/docker-compose.yml — Production Docker Compose configuration defining the backend API, frontend, and supporting services (database, Redis) that every contributor must understand for local development and deployment
• .github/workflows/pull-requests.yml — Primary CI/CD pipeline orchestrating backend/frontend tests, linting, and build validation that all PRs must pass
• dev/code-generation/main.py — Code generation entrypoint that auto-generates Python pytest routes and TypeScript types from OpenAPI schema, critical for maintaining API/frontend sync
• .github/copilot-instructions.md — Architectural guidance and contribution patterns that set expectations for code style, testing, and API design across the monorepo
• Taskfile.yml — Task automation file defining development workflows (build, test, lint, generate) that developers use daily
• .pre-commit-config.yaml — Git hooks configuration enforcing code quality checks (linting, formatting) before commits across Python and TypeScript
• crowdin.yml — Localization integration configuration managing multi-language support critical to Mealie's family-friendly UX

Add a new REST API endpoint for recipe operations

1. Define the request/response schema in OpenAPI specification or Pydantic model in the backend routes module (backend/app/routes/* (create or edit endpoint definition))
2. Implement the endpoint handler with business logic and database queries (backend/app/services/* (create or edit service layer))
3. Run code generation to auto-generate TypeScript types and pytest test stubs (dev/code-generation/main.py (execute with: python dev/code-generation/main.py))
4. Update pytest tests generated in /tests/integration/routes/ with actual test cases (dev/code-generation/templates/test_routes.py.j2 (generated tests in tests/))
5. Add corresponding Vue component or fetch call in frontend consuming the endpoint (frontend/src/* (create Vue component or composable))

Add a new recipe scraper or importer plugin

1. Create new scraper class inheriting from base scraper in backend with recipe extraction logic (backend/app/services/recipe_scraper.py (or new scraper module))
2. Register scraper in plugin registry or factory pattern (backend/app/services/* (update importer factory))
3. Add unit tests for HTML parsing and data extraction (tests/unit/services/test_scrapers.py (create test file))
4. Update API documentation and run code generation to expose scraper configuration endpoint (dev/code-generation/main.py (regenerate types and routes))

Add a new localization language

1. Configure language in Crowdin integration file (crowdin.yml (add language code and file mappings))
2. Run code generation to sync locale files from Crowdin or create locale JSON template (dev/code-generation/gen_ts_locales.py (execute to generate locale index))
3. Verify locale is available in frontend language selector component (frontend/src/components/* (update language menu if needed))
4. Test API responses and UI rendering with new locale (.github/workflows/locale-sync.yml (monitor sync workflow))

Add a new feature with backend+frontend integration

1. Create backend service/handler and define Pydantic schema for request/response (backend/app/services/your_feature.py (new service module))
2. Expose service via FastAPI router endpoint (backend/app/routes/your_feature.py (new or edit route))
3. Run code generation to auto-sync OpenAPI schema and generate TypeScript types (dev/code-generation/main.py (generates types in frontend/))
4. Create Vue component/page consuming generated API client (frontend/src/pages/YourFeature.vue (create new component))
5. Add tests: pytest for backend, Vitest/Jest for frontend (tests/ (add backend tests) and frontend/tests/ (add frontend tests))
6. Update CI pipeline if new external dependencies added (.github/workflows/pull-requests.yml (update if needed))

• FastAPI + Python — Type-safe REST API with automatic OpenAPI schema generation, enabling code generation and frontend type safety
• Vue 3 + TypeScript — Reactive UI framework with family-friendly UX; TypeScript types auto-generated from OpenAPI schema reduce bugs
• PostgreSQL/SQLite — Persistent relational storage for recipes, meal plans, users; supports complex queries for filtering/search
• Redis — In-memory cache reducing database load for recipe lists, session data; enables horizontal scaling
• Docker Compose — Multi-service orchestration for reproducible local dev and production deployments (backend, frontend, DB, cache)
• Crowdin — Centralized localization platform supporting multi-language family access without hardcoding translations
• Code generation (Jinja2 templates) — Auto-generates pytest routes and TypeScript types from OpenAPI schema, reducing manual sync and drift bugs

• Monorepo (backend + frontend in single repo)

  • Why: Tightly coupled API and UI; code generation requires schema co-location
  • Consequence: Simpler CI/CD and deployment, but larger repo and mixed language tooling complexity

• Auto-generated pytest tests from OpenAPI routes

  • Why: Maintain test coverage as API evolves without manual test duplication
  • Consequence: Tests may be generic/shallow; developers must enhance generated stubs with actual assertions

• Redis caching with cache invalidation on mutations

  • Why: Reduce DB load and improve recipe list response time
  • Consequence: Cache invalidation bugs possible; requires careful TTL/event-based invalidation design

• Recipe scraping via plugin architecture

  • Why: Support diverse recipe websites without core logic changes; extensible by community
  • Consequence: Fragile to website HTML structure changes; requires maintenance burden as sites update

• Multi-language support via Crowdin integration

  • Why: Family-friendly product requires global accessibility; crowdsourced translations scale beyond English
  • Consequence: Translation sync workflow complexity; English source changes require re-translation

• Real-time collaborative meal planning (no WebSocket live sync)
• Mobile-first native apps (responsive web UI only; third-party iOS shortcuts mentioned)
• Full-text search with advanced NLP (basic filtering/search only)
• Nutrition tracking or macro calculation (recipe import only,

1. Recipe scraper fragility: Dedicated bug report template (.github/ISSUE_TEMPLATE/recipe-scraper-bug.yaml) signals that URL parsing breaks frequently as recipe websites change structure—budget time for regex/selector maintenance. 2) Schema codegen synchronization: If you modify backend Pydantic models, you must regenerate TypeScript types via dev/code-generation/gen_ts_types.py or frontend will have stale types; this is easy to forget. 3) Monolithic coupling: Frontend and backend versions are tightly tied; breaking API changes require coordinated frontend updates. 4) Crowdin integration: Locale files are synced via Crowdin (crowdin.yml); manual translation edits may be overwritten on next sync. 5) Docker dependency: Dev environment relies on Docker (devcontainer.json); you must have Docker or Podman installed and running.

• Recipe URL scraping and structured data extraction — Core value proposition of Mealie; understanding CSS selectors, regex patterns, and fallback strategies for recipe parsing is essential for maintaining and improving the scraper module that users depend on
• OpenAPI/Swagger schema generation from type annotations — Mealie's REST API is auto-documented via FastAPI's Pydantic integration (seen in gen_py_schema_exports.py); understanding how type hints become API contracts helps maintain backward compatibility
• Frontend-backend code generation and type safety — The gen_ts_types.py script bridges Python and TypeScript; keeping frontend types in sync with backend schemas is non-obvious but critical—changes in Pydantic models must trigger regeneration
• Self-hosted vs. cloud-hosted architecture tradeoffs — Mealie's core differentiator is Docker-based self-hosting (multi-user, family-friendly); understanding deployment patterns, networking, and data persistence in containerized environments is relevant to contributing
• Internationalization (i18n) via external translation platforms — Mealie supports 35+ languages via Crowdin integration; changes that affect UI strings or require new translation keys must understand the crowdin.yml workflow to avoid breaking translations
• SQLAlchemy ORM for multi-user recipe databases — Backend persistence layer; understanding relationships (recipes → cookbooks → users, ingredients → units) helps with schema changes and migration safety
• GitHub Actions CI/CD orchestration and matrix testing — Project uses multiple workflows (test-backend.yml, test-frontend.yml, e2e.yml, publish.yml) for coordinated testing and release; understanding how to extend these pipelines is useful for adding new test suites or deployment targets

• tandoor/recipes — Direct competitor—Django-based self-hosted recipe manager with similar feature set (recipe import, meal planning, sharing); reference for feature parity and UX patterns
• grocy/grocy — Complementary self-hosted tool for grocery management and inventory; many Mealie users pair this with shopping list features
• sspat/recipe-scraper — Standalone Python library for recipe URL parsing; likely used or inspirational for Mealie's scraper module
• vue-community/awesome-vue — Ecosystem reference for Vue 3 + TypeScript patterns used in Mealie's frontend
• tiangolo/fastapi — Core backend framework (FastAPI) repository; reference for async patterns and OpenAPI schema generation used by Mealie's API

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add end-to-end tests for recipe scraper functionality

The repo has a recipe-scraper-bug.yaml issue template and scraper logic, but the e2e workflow (.github/workflows/e2e.yml) likely doesn't cover recipe import/scraping scenarios. This is critical since recipe scraping is a core feature mentioned in the README. Adding E2E tests for common recipe URLs (AllRecipes, BBC, etc.) would catch regressions early.

• [ ] Review .github/workflows/e2e.yml to identify gaps in recipe scraper coverage
• [ ] Identify the backend scraper code (likely in mealie/scrapers or similar)
• [ ] Add Playwright/Cypress tests to .github/workflows/e2e.yml that import recipes from 3-5 popular recipe sites
• [ ] Document test data URLs in dev/data or a dedicated test fixtures file

Add GitHub Action workflow for frontend accessibility testing

The repo has extensive frontend code (Vue, mentioned in README) with .github/workflows/test-frontend.yml, but there's no dedicated accessibility (a11y) testing workflow. Given Mealie is designed for family use, this is valuable. Tools like axe-core or Pa11y can be integrated to catch accessibility regressions automatically.

• [ ] Create .github/workflows/a11y.yml workflow file
• [ ] Integrate axe-core or Pa11y CLI as a linting step during frontend tests
• [ ] Configure rules to match recipe/meal planning UX needs (color contrast, form labels, etc.)
• [ ] Document accessibility guidelines in CONTRIBUTING.md or create ACCESSIBILITY.md

Add Python type hints and mypy validation for dev/code-generation scripts

The dev/code-generation directory contains Python utility scripts (utils/open_api_parser.py, utils/route.py, etc.) that lack type hints and aren't checked by the existing test-backend workflow. Adding mypy to .pre-commit-config.yaml and type hints would improve code maintainability and catch bugs in code generation logic that affects the entire backend.

• [ ] Review dev/code-generation/utils/.py and dev/code-generation/.py files for missing type hints
• [ ] Add mypy configuration to pyproject.toml or setup.cfg
• [ ] Add mypy check to .pre-commit-config.yaml
• [ ] Update dev/code-generation/main.py to use typed function signatures
• [ ] Verify code generation tests still pass in .github/workflows/test-backend.yml

• Add pytest tests for recipe scraper edge cases: The dedicated recipe-scraper-bug.yaml template suggests frequent scraper failures. Add parametrized pytest tests in tests/ for 5-10 real-world recipe websites (e.g., allrecipes.com, epicurious.com) to catch regressions early and document expected scraper behavior.: Medium
• Document API endpoint examples in code comments: The RestAPI backend generates types (gen_py_schema_exports.py, gen_ts_types.py) but endpoint usage examples are sparse. Add inline docstring examples to FastAPI route handlers showing request/response payloads for core endpoints (recipes CRUD, meal planner, shopping lists).: Low
• Create VSCode debug launch configuration documentation: .vscode/launch.json exists but is not documented in the repo. Write a short guide (Markdown) in docs/ or CONTRIBUTING explaining how to use the provided debug configs for both backend (FastAPI) and frontend (Vue) development, including breakpoint setup.: Low

The Mealie codebase demonstrates moderate security practices with GitHub Actions for automated testing and container scanning. However, there are notable gaps: the security policy only supports the latest version (creating risks for users on older releases), the vulnerability reporting mechanism uses a temporary email service, and container scanning appears to be only partial. The project would benefit from a more mature responsible disclosure program, comprehensive security documentation, and extended security support for multiple release versions. No critical vulnerabilities were identified in the visible structure, but a full code review of backend authentication, API endpoints, and dependency analysis would be required for complete assessment.

• Medium · Security Policy - No Version Support for Older Releases — SECURITY.md. The security policy states that only the latest version receives security patches and vulnerabilities are not back-ported. This creates a risk for users running older versions who cannot receive critical security fixes, leaving them vulnerable to known exploits. Fix: Consider implementing a security patch policy that covers at least the last 2-3 minor versions. Establish a clear deprecation timeline for older versions and communicate security updates proactively to users.
• Medium · Unclear Security Vulnerability Reporting Process — SECURITY.md. The security report mentions an email address (ob92oy0sl@mozmail.com) for sensitive vulnerabilities, but uses a disposable/temporary email service which may not be appropriate for a production application receiving security reports. This could lead to missed or compromised vulnerability disclosures. Fix: Use a permanent, dedicated security email address or establish a proper responsible disclosure program. Consider implementing a security.txt file (RFC 9116) at .well-known/security.txt to standardize vulnerability reporting.
• Medium · Docker Image Security Scanning Not Comprehensive — .github/workflows/partial-trivy-container-scanning.yml. The presence of 'partial-trivy-container-scanning.yml' suggests that container security scanning is only partially implemented, which may miss vulnerabilities in Docker images during the build pipeline. Fix: Implement comprehensive Trivy scanning for all container images. Ensure full vulnerability scanning is executed before publishing to registries and block deployment of images with critical vulnerabilities.
• Low · Pre-commit Configuration Present — .pre-commit-config.yaml. While a pre-commit configuration exists (.pre-commit-config.yaml), the actual security hooks and their configuration are not visible in the provided file structure, making it unclear if security-focused checks (secret scanning, dependency checking) are properly configured. Fix: Verify that security-focused pre-commit hooks are enabled, such as: detect-secrets, bandit (for Python), and dependency scanning tools. Document the security checks being performed.
• Low · API Security Documentation — docs/docs. No security.md or API security documentation visible in the /docs directory that would detail security best practices for API consumers, authentication mechanisms, rate limiting, or security headers. Fix: Create comprehensive security documentation covering: API authentication (OAuth/JWT), CORS policies, rate limiting, HTTPS requirements, and security headers. Document any breaking security changes prominently.
• Low · Code Generation Scripts May Require Security Review — dev/code-generation/. Code generation scripts in dev/code-generation/ (particularly gen_ts_types.py, gen_py_schema_exports.py) could potentially generate unsafe code if not properly configured, such as generating code with insecure defaults or schema vulnerabilities. Fix: Ensure all code generation scripts include proper input validation and sanitization. Review generated code for security issues. Consider implementing automated security scanning of generated code artifacts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.