AGENTS.md · mealie-recipes/mealie

Sections

1. Project Overview
2. Architecture & Key Patterns
3. Essential Commands (via Task/Taskfile.yml)
4. Critical Development Practices
5. Pull Request Best Practices
6. Common Gotchas
7. Key Files to Reference
8. Additional Resources

First lines (shown under the repo's AGPL-3.0 license)

# Mealie Development Guide for AI Agents

## Project Overview

Mealie is a self-hosted recipe manager, meal planner, and shopping list application with a FastAPI backend (Python 3.14) and Nuxt 4 frontend (Vue 3 + TypeScript). It uses SQLAlchemy ORM with support for SQLite and PostgreSQL databases.

**Development vs Production:**
- **Development:** Frontend (port 3000) and backend (port 9000) run as separate processes
- **Production:** Frontend is statically generated and served via FastAPI's SPA module (`mealie/routes/spa/`) in a single container

## Architecture & Key Patterns

### Backend Architecture (mealie/)

**Repository-Service-Controller Pattern:**
- **Controllers** (`mealie/routes/**/controller_*.py`): Inherit from `BaseUserController` or `BaseAdminController`, handle HTTP concerns, delegate to services
- **Services** (`mealie/services/`): Business logic layer, inherit from `BaseService`, coordinate repos and external dependencies
- **Repositories** (`mealie/repos/`): Data access layer using SQLAlchemy, accessed via `AllRepositories` factory
  - Get repos via dependency injection: `repos: AllRepositories = Depends(get_repositories)`
  - All repos scoped to group/household context automatically

**Route Organization:**
- Routes in `mealie/routes/` organized by domain (auth, recipe, groups, households, admin)
- Use `APIRouter` with FastAPI dependency injection
- Apply `@router.get/post/put/delete` decorators with Pydantic response models
- Route controllers use `HttpRepo` mixin for common CRUD operations (see `mealie/routes/_base/mixins.py`)

**Schemas & Type Generation:**
- Pydantic schemas in `mealie/schema/` with strict separation: `*In`, `*Out`, `*Create`, `*Update` suffixes
- Auto-exported from submodules via `__init__.py` files (generated by `task dev:generate`)
- TypeScript types auto-generated from Pydantic schemas - **never manually edit** `frontend/app/lib/api/types/`

**Database & Sessions:**
- Session management via `Depends(generate_session)` in FastAPI routes
- Use `session_context()` context manager in services/scripts
- SQLAlchemy models in `mealie/db/models/`, migrations in `mealie/alembic/`
- Create migrations: `task py:migrate -- "description"`

### Frontend Architecture (frontend/)

**Component Organization (strict naming conventions):**
- **Domain Components** (`components/Domain/`): Feature-specific, prefix with domain (e.g., `AdminDashboard`)
- **Global Components** (`components/global/`): Reusable primitives, prefix with `Base` (e.g., `BaseButton`)
- **Layout Components** (`components/Layout/`): Layout-only, prefix with `App` if props or `The` if singleton
- **Page Components** (`components/` with page prefix): Last resort for breaking up complex pages

**API Client Pattern:**
- API clients in `frontend/app/lib/api/` extend `BaseAPI`, `BaseCRUDAPI`, or `BaseCRUDAPIReadOnly`
- Types imported from auto-generated `frontend/app/lib/api/types/` (DO NOT EDIT MANUALLY)
- Composables in `frontend/app/composables/` for shared state and API logic (e.g., `use-mealie-auth.ts`)
- Use `useAuthBackend()` for authentication state, `useMealieAuth()` for user management

**State Management:**
- Nuxt 4 composables for state (no Vuex)
- Auth state via `use-mealie-auth.ts` composable
- Prefer composables over global state stores

## Essential Commands (via Task/Taskfile.yml)

**Development workflow:**
```bash
task setup              # Install all dependencies (Python + Node)
task dev:services       # Start Postgres & Mailpit containers
task py                 # Start FastAPI backend (port 9000)
task ui                 # Start Nuxt frontend (port 3000)
task docs               # Start Zensical documentation server
```

**Code generation (REQUIRED after schema changes):**
```bash
task dev:generate       # Generate TypeScript types, schema exports, test helpers
```

**Testing & Quality:**
```bash
task py:test            # Run pytest (supports args: task py:test -- -k test_name)
task py:check           # Format + lint + type-check + test (full validation)
task py:format          # Ruff format
task py:lint            # Ruff check
task py:mypy            # Type checking
task ui:test            # Vitest frontend tests
task ui:check           # Frontend lint + test
```

**Database:**
```bash
task py:migrate -- "description"  # Generate Alembic migration
task py:postgres        # Run backend with PostgreSQL config
```

**Docker:**
```bash
task docker:prod        # Build and run production Docker compose
```

## Critical Development Practices

### Python Backend

1. **Always use `uv` for Python commands** (not `python` or `pip`):
   ```bash
   uv run python mealie/app.py
   uv run pytest tests/
   ```

2. **Type hints are mandatory:** Use mypy-compatible annotations, handle Optional types explicitly

3. **Dependency injection pattern:**
   ```python
   from fastapi import Depends
   from mealie.repos.all_repositories import get_repositories, AllRepositories


   def my_route(repos: AllRepositories = Depends(get_repositories), user: PrivateUser = Depends(get_current_user)):
       recipe = repos.recipes.get_one(recipe_id)
   ```

4. **Settings & Configuration:**
   - Get settings: `settings = get_app_settings()` (cached singleton)
   - Get directories: `dirs = get_app_dirs()`
   - Never instantiate `AppSettings()` directly

5. **Testing:**
   - Fixtures in `tests/fixtures/`
   - Use `api_client` fixture for integration tests
   - Follow existing patterns in `tests/integration_tests/` and `tests/unit_tests/`

### Frontend

1. **Run code generation after backend schema changes:** `task dev:generate`

2. **TypeScript strict mode:** All code must pass type checking

3. **Component naming:** Follow strict conventions (see Architecture section above)

4. **API calls pattern:**
   ```typescript
   const api = useUserApi();
   const recipe = await api.recipes.getOne(recipeId);
   ```

5. **Composables for shared logic:** Prefer composables in `composables/` over inline code duplication

6. **Translations:** Only modify `en-US` locale files when adding new translation strings - other locales are managed via Crowdin and **must never be modified** (PRs modifying non-English locales will be rejected)

### Cross-Cutting Concerns

1. **Code generation is source of truth:** After Pydantic schema changes, run `task dev:generate` to update:
   - TypeScript types (`frontend/app/lib/api/types/`)
   - Schema exports (`mealie/schema/*/__init__.py`)
   - Test data paths and routes

2. **Multi-tenancy:** All data scoped to **groups** and **households**:
   - Groups contain multiple households
   - Households contain recipes, meal plans, shopping lists
   - Repositories automatically filter by group/household context

3. **Pre-commit hooks:** Install via `task setup:py`, enforces Ruff formatting/linting

4. **Testing before PRs:** Run `task py:check` and `task ui:check` before submitting PRs