Planie

Planie is a self-hosted, AI-assisted dinner planner for households that use Mealie as their recipe source and meal-plan destination.

It collects weekly preferences, uses an OpenAI-compatible LLM to suggest meals, lets you lock or override choices, reviews ingredient overlap, and pushes the confirmed dinner plan back to Mealie.

What Planie Does

• Uses Mealie as the recipe library and meal-plan write-back target.
• Uses Authentik/OpenID Connect for login.
• Stores household profile preferences such as dietary restrictions, disliked ingredients, cuisines, and time budget.
• Suggests weekly dinners with an LLM and falls back to rule-based suggestions when needed.
• Supports Fully Suggested and Fill the Gaps planning modes.
• Lets users select, regenerate, search overrides, mark nights off, and skip days.
• Reviews the final plan with meal dates, ingredient groups, and shared ingredient highlighting.
• Pushes confirmed dinner entries to Mealie.
• Tracks confirmed plans locally to support duplicate protection and post-week recipe rating prompts.

How Planning Works

1. Log in through Authentik or another OIDC-compatible provider.
2. Update your profile with household preferences.
3. Start a new plan and optionally rate meals from the previous plan.
4. Choose weekly planning preferences, such as time budget, pantry staples, cuisine mood, recency window, nights off, and notes.
5. Review the generated weekly grid.
6. Lock recipes, regenerate days, search for overrides, mark nights off, or skip days.
7. Open the review page to check selected meals and ingredient overlap.
8. Push the confirmed plan to Mealie.

Planning Modes

Fully Suggested

Planie generates a complete weekly grid up front. This is the fastest path when you want the app to make the first pass.

Fill the Gaps

Planie starts with an empty weekly grid. You can manually select meals first, then ask Planie to suggest the remaining open days.

Important Behavior

• Planie plans dinners only.
• planie-exclude tagged recipes are filtered out of planning suggestions.
• Recipes containing configured dietary restrictions are filtered from planning suggestions.
• Recipe detail pages may still show dietary warnings for saved recipes that are not suggested.
• If the LLM is unavailable or returns invalid JSON during plan generation, Planie uses fallback suggestions.
• If Mealie is unavailable, Planie shows a clear connection error instead of failing silently.
• Confirmed plans are persisted locally in SQLite for duplicate-confirmation protection and future feedback prompts.
• Changing APP_SECRET_KEY invalidates existing sessions.

Deployment

Planie is intended to run behind HTTPS with a reverse proxy such as Caddy.

Recommended deployment paths:

• Docker Compose for a single-host deployment.
• The included Ansible role under roles/planie/ for repeatable host setup.

Quick Docker Compose start:

cp .env.example .env
docker compose up --build -d

Before starting, edit .env with real Mealie, OIDC, LLM, and app secret values.

Detailed deployment documentation:

• docs/deployment.md - Docker Compose, reverse proxy, Ansible role, persistence, health checks, and upgrades.
• docs/deployment-authentik.md - Authentik OAuth2/OIDC provider setup.
• docs/manual-e2e-checklist.md - Manual validation checklist for a deployed instance.

Upgrading

For Docker Compose deployments:

git pull --ff-only
docker compose up --build -d

Before upgrading:

• Back up the SQLite database or the Docker volume that contains it.
• Review .env.example for new configuration variables.
• Keep APP_SECRET_KEY unchanged unless you intentionally want to invalidate sessions.

For Ansible deployments, update the image or repo source used by your inventory and re-run the planie role. See docs/deployment.md.

Configuration

Use .env.example as the configuration reference. Do not commit real .env files or secrets.

Variable	Purpose
MEALIE_BASE_URL	Base URL for the Mealie instance.
MEALIE_API_KEY	Mealie API token. Keep secret.
MEALIE_HISTORY_WEEKS	Number of past weeks used for recency/history.
LLM_PROVIDER	Provider label: llamacpp, openai, or anthropic.
LLM_BASE_URL	Optional OpenAI-compatible API base URL.
LLM_MODEL	Chat model name sent to the provider.
LLM_API_KEY	Optional LLM API key. Keep secret when used.
LLM_TIMEOUT_SECONDS	LLM request timeout.
LLM_RETRY_COUNT	Retry count for transient LLM failures.
APP_SECRET_KEY	Session signing key. Keep secret and stable across restarts.
APP_HOST	Local bind host when running directly.
APP_PORT	Local or Compose host port.
OIDC_CLIENT_ID	OIDC client ID.
OIDC_CLIENT_SECRET	OIDC client secret. Keep secret.
OIDC_DISCOVERY_URL	OIDC discovery metadata URL.
OIDC_REDIRECT_URI	Callback URL, usually https://<domain>/auth/callback.
DB_PATH	SQLite database path. In Docker, use /app/data/planie.db.
PLAN_WEEK_START	Week start day, for example monday.

Data And Persistence

Planie stores local application data in SQLite. In Docker, the database lives at /app/data/planie.db and should be backed by the planie_data volume.

Back up the SQLite database before host migrations, volume changes, or major upgrades.

Documentation

• docs/deployment.md - Deployment, upgrades, reverse proxy, Ansible, and operations.
• docs/deployment-authentik.md - Authentik setup.
• docs/manual-e2e-checklist.md - Manual deployed-instance validation.
• docs/development.md - Local development, repository layout, and automated tests.
• Specs/roadmap.md - Completed build roadmap and remaining operational questions.

Known Operational Follow-Ups

• Confirm Paprika-to-Mealie migration status before relying heavily on ratings.
• Tune the LLM prompt against the deployed local model.
• Validate Mealie API endpoint paths against the exact deployed Mealie version.