# mealie-recipes/mealie architecture

> Architecture diagram of the GitHub repository mealie-recipes/mealie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mealie-recipes/mealie
- Repository: https://github.com/mealie-recipes/mealie

## Overview

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: [`mealie/services`](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services) (Service Layer), [`mealie/routes`](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/routes) (HTTP Routes), [`frontend/app`](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app) (Nuxt App), [`frontend/app/lib/api`](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/lib/api) (API Clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Nuxt App<br/>ui shell"]
  node_frontend_domain_ui["Domain UI<br/>feature views"]
  node_frontend_components["UI Components<br/>vue components"]
  node_frontend_api["API Clients<br/>typed clients"]
  node_frontend_composables["State Composables<br/>client logic"]
  node_frontend_server["Nuxt Server<br/>proxy layer"]
end

subgraph group_backend["Backend"]
  node_backend_entry["App Entry<br/>fastapi app<br/>[app.py]"]
  node_backend_routes["HTTP Routes<br/>api surface"]
  node_backend_route_base["Route Base<br/>controller plumbing"]
  node_backend_services["Service Layer<br/>orchestration"]
  node_backend_recipe["Recipe Core<br/>domain service"]
  node_backend_household_group["Group & Household<br/>multi-tenant domain"]
  node_backend_auth_user["Auth & Users<br/>identity domain"]
  node_backend_persistence[("Persistence<br/>database layer")]
  node_backend_schema["Schemas<br/>contracts"]
  node_backend_background["Background Jobs<br/>scheduler/events"]
  node_backend_integrations["Integrations<br/>external adapters"]
end

subgraph group_ops["Ops & Tooling"]
  node_ops_docs["Docs Site<br/>documentation"]
  node_ops_codegen["Codegen<br/>generated artifacts"]
  node_ops_deploy["Deploy & CI<br/>ops pipeline"]
end

node_frontend_app -->|"renders"| node_frontend_domain_ui
node_frontend_app -->|"uses"| node_frontend_components
node_frontend_app -->|"drives"| node_frontend_composables
node_frontend_composables -->|"calls"| node_frontend_api
node_frontend_api -->|"proxies"| node_frontend_server
node_frontend_api -->|"requests"| node_backend_routes
node_frontend_server -->|"forwards"| node_backend_routes
node_backend_entry -->|"mounts"| node_backend_routes
node_backend_routes -->|"shares"| node_backend_route_base
node_backend_routes -->|"validates"| node_backend_schema
node_backend_routes -->|"orchestrates"| node_backend_services
node_backend_services -->|"coordinates"| node_backend_recipe
node_backend_services -->|"coordinates"| node_backend_household_group
node_backend_services -->|"depends on"| node_backend_auth_user
node_backend_services -->|"persists"| node_backend_persistence
node_backend_services -->|"emits"| node_backend_background
node_backend_services -->|"integrates"| node_backend_integrations
node_backend_persistence -.->|"maps through"| node_backend_schema
node_backend_background -->|"cleans"| node_backend_persistence
node_ops_codegen -->|"generates"| node_frontend_api
node_ops_codegen -->|"derives"| node_backend_schema
node_ops_docs -.->|"documents"| node_backend_routes
node_ops_deploy -.->|"packages"| node_backend_entry
node_ops_deploy -.->|"packages"| node_frontend_app

click node_frontend_app "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app"
click node_frontend_domain_ui "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/pages"
click node_frontend_components "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/components"
click node_frontend_api "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/lib/api"
click node_frontend_composables "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/composables"
click node_frontend_server "https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/server"
click node_backend_entry "https://github.com/mealie-recipes/mealie/blob/mealie-next/mealie/app.py"
click node_backend_routes "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/routes"
click node_backend_route_base "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/routes/_base"
click node_backend_services "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services"
click node_backend_recipe "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/recipe"
click node_backend_household_group "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/group_services"
click node_backend_auth_user "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/core/security"
click node_backend_persistence "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/db"
click node_backend_schema "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/schema"
click node_backend_background "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/scheduler"
click node_backend_integrations "https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/openai"
click node_ops_docs "https://github.com/mealie-recipes/mealie/tree/mealie-next/docs/docs"
click node_ops_codegen "https://github.com/mealie-recipes/mealie/tree/mealie-next/dev/code-generation"
click node_ops_deploy "https://github.com/mealie-recipes/mealie/tree/mealie-next/docker"

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_frontend_app,node_frontend_domain_ui,node_frontend_components,node_frontend_api,node_frontend_composables,node_frontend_server toneBlue
class node_backend_entry,node_backend_routes,node_backend_route_base,node_backend_services,node_backend_recipe,node_backend_household_group,node_backend_auth_user,node_backend_persistence,node_backend_schema,node_backend_background,node_backend_integrations toneAmber
class node_ops_docs,node_ops_codegen,node_ops_deploy toneMint
```

## Components

### Frontend

Nuxt/Vue application, client API wrappers, and lightweight server-side routes.

- [Nuxt App](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app): ui shell · Main frontend application with pages, layouts, components, plugins, and middleware. · `frontend/app`
- [Domain UI](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/pages): feature views · Recipe, shopping list, household, group, admin, and user screens organized by domain. · `frontend/app/pages`
- [UI Components](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/components): vue components · Reusable global controls and domain-specific widgets used across the app. · `frontend/app/components`
- [API Clients](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/lib/api): typed clients · Generated and hand-written REST wrappers used by composables and pages. · `frontend/app/lib/api`
- [State Composables](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/app/composables): client logic · Domain-focused composables for recipes, shopping lists, users, groups, and stores. · `frontend/app/composables`
- [Nuxt Server](https://github.com/mealie-recipes/mealie/tree/mealie-next/frontend/server): proxy layer · 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](https://github.com/mealie-recipes/mealie/blob/mealie-next/mealie/app.py): fastapi app · Backend application bootstrap and main entrypoints. · `mealie/app.py`
- [HTTP Routes](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/routes): api surface · Domain route modules for auth, admin, recipes, groups, households, users, organizers, parsing, media, units, explore, and SPA/static delivery. · `mealie/routes`
- [Route Base](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/routes/_base): controller plumbing · Shared router/controller helpers, checks, and composition utilities. · `mealie/routes/_base`
- [Service Layer](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services): orchestration · Business workflows that coordinate routes, repositories, integrations, and background tasks. · `mealie/services`
- [Recipe Core](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/recipe): domain service · Recipe CRUD, bulk actions, data shaping, templates, scraping, parsing, and exports. · `mealie/services/recipe`
- [Group & Household](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/group_services): multi-tenant domain · Shared household and group services for meal plans, shopping lists, webhooks, notifications, preferences, reports, and AI providers. · `mealie/services/group_services`
- [Auth & Users](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/core/security): identity domain · Authentication providers, security, registration, password reset, API tokens, and user management. · `mealie/core/security`
- [Persistence](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/db): database layer · SQLAlchemy models, repositories, Alembic migrations, and database setup. · `mealie/db`
- [Schemas](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/schema): contracts · Request/response and domain schemas that bridge HTTP and persistence. · `mealie/schema`
- [Background Jobs](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/scheduler): scheduler/events · Scheduler, event bus, and delayed side-effect tasks such as cleanup, webhooks, and timeline events. · `mealie/services/scheduler`
- [Integrations](https://github.com/mealie-recipes/mealie/tree/mealie-next/mealie/services/openai): external adapters · OpenAI, email, backup/export, scraping, and storage-related adapters. · `mealie/services/openai`

### Ops & Tooling

Container, docs, generation, and repository automation.

- [Docs Site](https://github.com/mealie-recipes/mealie/tree/mealie-next/docs/docs): documentation · MkDocs documentation and contributor guides. · `docs/docs`
- [Codegen](https://github.com/mealie-recipes/mealie/tree/mealie-next/dev/code-generation): generated artifacts · Scripts that generate API typings, locale bundles, and test/support artifacts. · `dev/code-generation`
- [Deploy & CI](https://github.com/mealie-recipes/mealie/tree/mealie-next/docker): ops pipeline · Docker, devcontainer, release automation, and GitHub Actions workflows. · `docker`

## Connections

- 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.
