How mealie-recipes/mealie works
1. High-level shape
Mealie is a self-hosted, full-stack recipe management system with two major runtimes: a Python backend and a Nuxt/Vue frontend. The backend owns business logic, persistence, auth, and integrations; the frontend owns the user experience and calls the backend through generated API clients and a small server-side proxy layer.
2. Frontend boundary
The frontend/app tree is a standard Nuxt application organized by domain: pages, components, composables, layouts, middleware, plugins, and lib/api. The UI is split into recipe, shopping list, household, group, admin, and user areas, with route guards for permissions such as admin-only, group-only, and household-management access. The frontend also contains locale files, theming, and reusable global UI controls.
3. Frontend-to-backend data flow
Frontend pages and composables use strongly typed API wrappers in frontend/app/lib/api and frontend/app/composables/api to talk to backend REST endpoints. The frontend includes a lightweight server layer (frontend/server/api, frontend/server/routes) that proxies or exposes supporting routes such as docs and OpenAPI JSON. This means most domain data still originates from the Python API, not from client-side state alone.
4. Backend entry and API surface
The backend is centered in mealie/app.py and mealie/main.py, with route modules under mealie/routes. Routes are grouped by domain rather than by HTTP verb: auth, admin, recipes, groups, households, users, organizers, parsing, media, unit/food management, public explore, and SPA/static routes. routes/_base provides shared controller/router plumbing, checks, and route composition.
5. Application/service layer
Most business logic lives in mealie/services, which acts as the orchestration layer between routes, repositories, external services, and background jobs. Important service clusters include recipe CRUD/import/export, meal planning, shopping lists, household/group services, AI/OpenAI integration, scraping, user registration/password flows, backups, migrations from other apps, and scheduling. This layer is where workflows are assembled before persistence changes are made.
6. Persistence and domain model
Data is modeled in mealie/db/models and accessed through mealie/repos. The repository layer is split by domain (recipes, users, group, household, etc.) and isolates queries from services/controllers. Schema/validation objects in mealie/schema sit between HTTP and the domain model, shaping request/response payloads and API contracts. Alembic migrations under mealie/alembic define the evolving database structure.
7. Core domain boundaries
The application is organized around several durable boundaries: recipes and their ingredients/instructions/assets; organizers such as categories, tags, tools, foods, units, and labels; households for shared operational features like meal plans, shopping lists, webhooks, and notifications; groups for broader multi-user settings, exports, reports, AI providers, and preferences; and users/admin for identity, permissions, and site management. That separation is visible consistently across routes, services, repos, schemas, and frontend pages.
8. Ingestion and content processing
Recipe creation is not just CRUD; it includes multiple ingestion paths. The scraper/parser services handle recipe import from URLs, HTML, images, videos, and AI-assisted parsing via OpenAI. There are also migration services for importing from other recipe systems, plus bulk actions and export paths. This ingestion pipeline feeds normalized recipe data into the same persistent model used by manual editing.
9. Background work and eventing
Scheduled and asynchronous behavior is handled by mealie/services/scheduler and the event bus service. Background tasks cover things like timeline event creation, deleting stale shopping items, purging expired share tokens, cleaning old exports/password resets/registrations, posting webhooks, and resetting locked users. The event bus connects domain events to listeners, which is important for side effects that should not block request handling.
10. Security and authentication
Auth is a first-class subsystem in mealie/core/security and mealie/routes/auth. The project supports multiple authentication providers, including credentials, LDAP, and OpenID/OIDC, and also manages tokens, password hashing, reset flows, and permission checks. Access control is reinforced both at the backend route level and in the frontend middleware/layout decisions.
11. External integrations and storage
Material external dependencies include OpenAI, email delivery, LDAP/OIDC identity providers, and likely filesystem-backed media/storage for user and recipe assets. The backup system exports database/application state to archive files, and the app supports both SQLite and PostgreSQL deployment modes, which affects persistence and migration behavior.
12. Localization and generated artifacts
Localization is deeply integrated: both backend and frontend ship large locale/message sets, and dev/code-generation produces TypeScript/Python artifacts from API and locale sources. This indicates that some parts of the architecture are contract-driven and generated rather than hand-maintained, especially around API typing and translated UI strings.
13. Deployment and operational shape
The repo is designed for containerized self-hosting. There are Dockerfiles, compose files, a devcontainer, and GitHub Actions for building, testing, publishing, security scanning, docs, and release automation. Operationally, the app is meant to be run as a backend service plus a frontend app, with the backend owning the persistent state and the frontend serving the interactive UI.
Main entry points: services Service Layer · routes HTTP Routes · app Nuxt App · api API Clients
Components 20
Frontend
Nuxt/Vue application, client API wrappers, and lightweight server-side routes.
- Nuxt App · Main frontend application with pages, layouts, components, plugins, and middleware.
frontend/app - Domain UI · Recipe, shopping list, household, group, admin, and user screens organized by domain.
frontend/app/pages - UI Components · Reusable global controls and domain-specific widgets used across the app.
frontend/app/components - API Clients · Generated and hand-written REST wrappers used by composables and pages.
frontend/app/lib/api - State Composables · Domain-focused composables for recipes, shopping lists, users, groups, and stores.
frontend/app/composables - Nuxt Server · Server routes and API proxy endpoints that support docs and OpenAPI exposure.
frontend/server
Backend
Python API, domain services, persistence, and runtime infrastructure.
- App Entry · Backend application bootstrap and main entrypoints.
mealie/app.py - HTTP Routes · Domain route modules for auth, admin, recipes, groups, households, users, organizers, parsing, media, units, explore, and SPA/static delivery.
mealie/routes - Route Base · Shared router/controller helpers, checks, and composition utilities.
mealie/routes/_base - Service Layer · Business workflows that coordinate routes, repositories, integrations, and background tasks.
mealie/services - Recipe Core · Recipe CRUD, bulk actions, data shaping, templates, scraping, parsing, and exports.
mealie/services/recipe - Group & Household · Shared household and group services for meal plans, shopping lists, webhooks, notifications, preferences, reports, and AI providers.
mealie/services/group_services - Auth & Users · Authentication providers, security, registration, password reset, API tokens, and user management.
mealie/core/security - Persistence · SQLAlchemy models, repositories, Alembic migrations, and database setup.
mealie/db - Schemas · Request/response and domain schemas that bridge HTTP and persistence.
mealie/schema - Background Jobs · Scheduler, event bus, and delayed side-effect tasks such as cleanup, webhooks, and timeline events.
mealie/services/scheduler - Integrations · OpenAI, email, backup/export, scraping, and storage-related adapters.
mealie/services/openai
Ops & Tooling
Container, docs, generation, and repository automation.
- Docs Site · MkDocs documentation and contributor guides.
docs/docs - Codegen · Scripts that generate API typings, locale bundles, and test/support artifacts.
dev/code-generation - Deploy & CI · Docker, devcontainer, release automation, and GitHub Actions workflows.
docker
Connections 24
- Nuxt App → Domain UI: renders · Pages define the user-facing routes and screens.
- Nuxt App → UI Components: uses · Pages and layouts compose shared and domain-specific components.
- Nuxt App → State Composables: drives · Composable state and domain logic power page behavior.
- State Composables → API Clients: calls · Composable logic invokes typed API wrappers for backend data.
- API Clients → Nuxt Server: proxies · Frontend server routes expose supporting endpoints and docs.
- API Clients → HTTP Routes: requests · Client API wrappers target the Python REST surface.
- Nuxt Server → HTTP Routes: forwards · Server-side proxy routes pass through to backend APIs when needed.
- App Entry → HTTP Routes: mounts · Application bootstrap registers the route modules.
- HTTP Routes → Route Base: shares · Route modules rely on shared controller and router plumbing.
- HTTP Routes → Schemas: validates · HTTP handlers use schemas for request and response shaping.
- HTTP Routes → Service Layer: orchestrates · Routes delegate business workflows to services.
- Service Layer → Recipe Core: coordinates · Recipe workflows cover CRUD, parsing, scraping, and export.
- Service Layer → Group & Household: coordinates · Group and household workflows manage shared multi-user features.
- Service Layer → Auth & Users: depends on · User-facing workflows rely on security and identity services.
- Service Layer → Persistence: persists · Services store and query domain state through repositories and models.
- Service Layer → Background Jobs: emits · Services hand off async side effects to scheduler and events.
- Service Layer → Integrations: integrates · Business logic talks to OpenAI, email, backups, and scraping adapters.
- Persistence → Schemas: maps through · Schemas sit between HTTP contracts and stored domain entities.
- Background Jobs → Persistence: cleans · Jobs prune stale records and maintain derived state.
- Codegen → API Clients: generates · Code generation produces typed frontend API and locale artifacts.
- Codegen → Schemas: derives · Generated backend schema exports and route fixtures track API contracts.
- Docs Site → HTTP Routes: documents · Docs describe API usage, auth, installation, and operations.
- Deploy & CI → App Entry: packages · Docker and release tooling build and run the backend service.
- Deploy & CI → Nuxt App: packages · Container and CI tooling build and run the frontend app.