Mealie

Mealie is a fully self‑hosted recipe management system that exposes a RESTful API for programmatic access while delivering a reactive Vue‑based frontend. The application is designed to be lightweight yet feature rich, enabling developers to embed recipe data, meal plans, and shopping lists into larger home‑automation or kitchen‑display stacks. At its core, Mealie functions as a CRUD platform for recipe objects, with auxiliary modules for scheduling (meal planner), inventory (shopping list), and organization (cookbooks). The architecture emphasizes a clear separation between the API layer and the UI layer, allowing each to be scaled independently.

Architecture & Technical Stack

• Backend: Python 3.11 running on FastAPI – the async web framework that powers the REST endpoints, authentication (JWT/OAuth), and background tasks such as recipe scraping.
• Database: PostgreSQL (recommended) with optional SQLite for lightweight deployments. SQLAlchemy is used as the ORM, providing declarative models and migrations via Alembic.
• Frontend: Vue 3 with Composition API, leveraging Pinia for state management and Vite as the build tool. The UI communicates with the backend solely over HTTPS using JSON payloads.
• Containerization: Official Docker images are published to GitHub Container Registry and Docker Hub. A docker-compose.yml template is provided, encapsulating the API, a PostgreSQL service, and optional Redis for caching.
• Background Workers: Celery (with Redis broker) handles long‑running tasks such as fetching recipe data from external URLs, converting units, and sending webhook notifications.

Core Capabilities & APIs

• Recipe Import Engine: Exposes an endpoint /import that accepts a URL; the backend scrapes metadata, images, and ingredient lists using a pluggable parser architecture (supports major recipe sites out of the box).
• Meal Planner API: CRUD operations for weekly plans, including scheduling recipes to specific dates and times. Supports recurring patterns via cron‑style expressions.
• Shopping List Generation: Aggregates ingredients across planned meals, grouping them by supermarket sections. The API /shopping-list returns a JSON structure that can be rendered in custom UIs or exported to CSV.
• Cookbook Management: Tag‑based grouping of recipes; the API allows nested cookbooks and hierarchical organization.
• Webhooks & Event Hooks: Developers can register endpoints to receive POST notifications on recipe creation, update, or deletion, enabling integration with external services (e.g., voice assistants, home‑automation hubs).
• Authentication & Authorization: Supports OAuth2 password flow and JWT tokens, with role‑based access controls (admin vs. user). The API is fully documented via OpenAPI/Swagger, auto‑generated from FastAPI.

Deployment & Infrastructure

• Self‑Hosting: The application can run on any machine that supports Docker, or directly via Python. Minimal external dependencies beyond PostgreSQL and Redis.
• Scalability: The stateless API can be horizontally scaled behind a reverse proxy (NGINX, Traefik). Celery workers can be added in parallel to handle increased import or webhook load.
• High Availability: PostgreSQL replication and Redis Sentinel can be configured for fault tolerance. Docker Swarm or Kubernetes manifests are available in the repo for orchestrated deployments.
• Resource Footprint: A single container instance typically consumes <200 MiB RAM and <1 CPU core, making it suitable for Raspberry Pi or NAS environments.

Integration & Extensibility

• Plugin System: Mealie ships with a lightweight plugin API that allows developers to hook into the import pipeline, add custom UI components, or extend data models without modifying core code.
• Custom Parsers: Implement a new parser by subclassing the base RecipeParser interface; register it in the configuration to support niche recipe sites or local YAML files.
• External API Consumption: The public REST endpoints can be consumed by mobile apps, smart displays, or voice assistants. The OpenAPI spec facilitates automatic client generation in languages like TypeScript, Go, or Java.
• Webhooks: Register any URL to receive real‑time events; useful for syncing with grocery delivery services or calendar apps.

Developer Experience

• Documentation: The official docs (https://docs.mealie.io) cover architecture, API usage, deployment guides, and plugin development. The OpenAPI spec is live at /docs when the server runs.
• Community & Support: Active Discord channel, issue tracker, and contributor guide. The project follows semantic versioning and publishes nightly builds for early adopters.
• Configuration: All settings are exposed via environment variables or a .env file, making CI/CD pipelines straightforward. The config schema is validated by Pydantic.
• Testing: Unit tests are written with pytest, and the repository includes a GitHub Actions workflow for continuous integration.

Use Cases

Advantages Over