Listly

Self-hosted household management — shared shopping lists, a recipe cookbook, and everything scoped per household. You can be in multiple households at once and switch between them freely.

What it does

• Shopping lists — everyone in the household sees the same list. Items show who added them and who checked them off.
• Recipe cookbook — per-household recipes with URL import, cover images, nutrition info, ingredients and step-by-step instructions. One button pushes all ingredients straight to the shopping list.
• Meal planner — plan meals by day in daily, weekly, or monthly view. Link a plan to an existing recipe or write it manually. Supports per-user and household-wide scopes, drag-and-drop to reorder or move plans between days, multi-select delete, a detail sheet that links back to the recipe, and a delete button directly on the detail modal.
• Storage inventory — track what you have at home across named locations (Fridge, Freezer, Pantry, etc.). Set a low-stock threshold per item and get an amber banner when something's running low. Drag items between locations. One click pushes low items straight to the shopping list.
• Multiple households — create or join as many as you want, switch instantly in the sidebar.
• Roles — four levels per household: owner, admin, member, restricted. Each one unlocks different things.
• Invite links — one-time links for adding new users, generated by admins.
• Modules — all four modules can be toggled on/off globally by an admin, and individually per user.
• English + German — auto-detected from the browser, switchable in settings.
• PWA — installs as an app, works offline with cached data.
• Dark only — no light mode, no toggle.

Stack

Layer	Tech
Frontend	Vue 3, Vite, Pinia, Vue Router, Vue i18n
Backend	Python 3.12, Flask, SQLite
Auth	JWT (PyJWT), PBKDF2-SHA256
Serving	Gunicorn (2 workers)
Container	Docker, multi-stage build

Running with Docker

cp docker/.env.example docker/.env
# open docker/.env and set SECRET_KEY and HOST_PORT

cd docker
docker compose up -d --build

First time you open it in the browser it'll take you through a setup wizard to create the admin account. Full details in doc/DEPLOYMENT.md.

Running locally

Backend

cd backend
pip install -r requirements.txt
export SECRET_KEY=dev-secret
python main.py

Frontend (separate terminal)

cd frontend
npm install
npm run dev   # Vite on :5173, proxies /api → :5000

For a production-style build run npm run build in frontend/ — Flask will serve dist/index.html for everything that isn't an API route.

Project layout

Listly/
├── backend/
│   ├── api/
│   │   ├── auth/           # login, register, token
│   │   ├── households/     # create, join, settings, members
│   │   ├── shopping/       # list, add, check, delete items
│   │   ├── recipes/        # CRUD, import, push-to-list, favorites
│   │   ├── mealplanner/    # plans CRUD, bulk delete, reorder
│   │   ├── storage/        # locations + items CRUD
│   │   ├── modules/        # per-user and global module toggles
│   │   └── …               # invites, users, settings, uploads
│   ├── core/       # config, security helpers, utilities
│   ├── db/         # schema, migration runner, row→dict helpers
│   ├── lang/       # backend i18n strings (en_US / de_DE)
│   └── app.py      # application factory
│
├── frontend/
│   └── src/
│       ├── views/
│       │   ├── MealPlannerView.vue   # daily / weekly / monthly calendar
│       │   ├── StorageView.vue       # inventory with location sections
│       │   └── …                     # shopping, recipes, profile, admin…
│       ├── components/
│       │   ├── PlanCard.vue          # reusable meal plan card
│       │   └── …                     # AppIcon, Avatar, Pill, etc.
│       ├── stores/
│       │   ├── mealplan.js           # meal plan state + API calls
│       │   ├── storage.js            # locations + items state + API calls
│       │   └── …                     # auth, household, recipes
│       └── lang/       # translation files (en-US, de-DE)
│
├── docker/
│   ├── Dockerfile          # Node build → Python/Gunicorn
│   └── docker-compose.yml
│
└── doc/            # all documentation lives here

Roles

Role	Permissions
owner	full control — rename/delete household, change anyone's role
admin	kick members, edit/delete any recipe
member	add/edit recipes, manage shopping list
restricted	view only

There's also a global admin flag on user accounts (separate from household roles) that gives access to the instance admin panel.

Ideas & Roadmap

Shopping

• Multiple lists per household — named lists like "Weekly" or "Hardware Store"
• Frequent items — suggest items based on history while typing
• Category grouping — collapse the list by category (Dairy, Produce, etc.)
• Barcode scanner — scan barcodes on mobile to add items by name
• Budget tracking — attach prices and show a running total
• QR code sharing — generate a QR for the current list

Recipes

• Scaling — adjust quantities by target serving count
• Favourites — star recipes for quick access
• Ratings — 1–5 star ratings per household
• Collections — group recipes by tag or custom category
• Meal planner — assign recipes to days in a full calendar view

Meal Planner

• Daily / Weekly / Monthly views — switch between three calendar layouts
• Recipe plans — link any recipe from the household cookbook
• Manual plans — freeform title and description, no recipe required
• Mine / Household scope — see just your plans or everyone's
• Drag-and-drop reorder — rearrange plans within a day
• Drag between days — move a plan to a different day by dragging it across columns or cells
• Drag-over highlight — dashed accent outline shows the target day while dragging
• Delete from detail — trash button directly on the plan detail modal, no need to open the editor
• Click to select day — click anywhere on a day column (weekly) or cell (monthly) to select it
• Multi-select delete — long-press or right-click to select, then bulk delete
• Generate shopping list — push all ingredients from a week's plan to the list in one go
• Recurring plans — repeat a plan every week automatically

Storage

• Locations — organise items into named rooms (Fridge, Freezer, Pantry, etc.) with icons and colour coding
• Stock tracking — track quantity and unit per item
• Low-stock alerts — set a threshold; items below it show an amber badge and appear in the banner
• Push to shopping list — add low-stock items (or any item) to the shopping list in one click
• Drag between locations — drag an item from one location section to another; dashed outline highlights the target
• Expiry dates — track best-before dates and highlight anything expiring soon
• Barcode lookup — scan a barcode to auto-fill the item name

Notifications

• Web push — alert members when items are added or the list is cleared
• Activity feed — recent household activity in-app

Auth & Users

• OAuth — sign in with Google or GitHub
• 2FA — TOTP-based two-factor auth
• Self-deletion — let users delete their own account from profile settings
• More languages — French, Spanish, etc.

Infrastructure

• S3 storage — store uploaded images in S3 or compatible object storage
• Export/import — shopping list as PDF/CSV, recipes as JSON
• Backup button — download a full DB backup from the admin panel
• Real-time sync — WebSocket or SSE instead of polling
• Multi-arch Docker image — amd64 + arm64 for Raspberry Pi hosting

---

Docs

File	What's in it
doc/ARCHITECTURE.md	how the system fits together
doc/DEPLOYMENT.md	Docker setup, env vars, backups, nginx
doc/API.md	full API reference
backend/doc/README.md	backend layout and conventions
backend/doc/DATABASE.md	schema, booleans, migrations
backend/doc/AUTH.md	JWT, decorators, roles, invite flow
frontend/doc/README.md	frontend layout, routing, design system
frontend/doc/STORES.md	Pinia store reference
frontend/doc/COMPONENTS.md	component props and usage
frontend/doc/VIEWS.md	what each view does