FamilyWell

The family organizer for the people you live with. Shared shopping lists, to-dos, a family calendar, spending, projects, recipes, the car and more, in one installable app. A small, stable core with self-contained modules you switch on per family, so each household only sees what it uses.

Self-host it for your own family, or use the hosted version at familywell.co (there's a one-click live demo).

Source-available, not open source. FamilyWell is free for personal, noncommercial use: run it for your own family, change it, learn from it. Commercial use and reselling are not allowed. See License.

What you get

• Families, not just accounts. Invite the people you live with; everyone shares the same data, with roles (admin / member).
• Modules you switch on per family (Settings → Modules). Bundled:
  • Shopping: several shared lists, grouped by aisle per shop, a "shopping mode", voice and paste input.
  • Tasks: shared to-do lists with sub-tasks, due dates and assignees, plus important and recurring to-dos.
  • Calendar: month and timeline views, repeating events, people and to-dos on events. Task due dates, birthdays, car due dates and project starts show up on their own. Includes a private subscribe link for Google or Apple Calendar.
  • Spending: quick-add expenses, categories, shared trackers with automatic "who owes whom", multi-currency, receipt photos and optional AI receipt scanning.
  • Projects: the bigger things a family works on, with tasks, progress and linked shopping lists.
  • Recipes: family recipes with a calculator (scale by servings, total amount or what you have) and add-to-shopping.
  • Notes, Contacts, Birthdays, Inventory (what's in the house and what's running low) and Vehicles (mileage, maintenance, documents).
• A home screen that brings it together: this month's spending, what's on now and next, birthdays, and what's due today and this week.
• Granular sharing: anything shareable can be family-wide, invited-only or private, with per-person roles and read-only public links.
• Works with AI assistants: a built-in MCP server lets Claude, ChatGPT and other MCP clients read and update your family's lists, calendar and more, with per-module permissions you pick when you connect. Interactive widgets render right in the chat.
• Realtime and installable: changes appear live for everyone (Laravel Reverb), and it installs to your home screen as a PWA.
• Two languages so far: English and Romanian, per person.

Tech stack

One Docker image runs the same way self-hosted and in the cloud.

Quick start (local development)

Prerequisites: PHP 8.2+, Composer, Node 22+, and npm. No database server needed, local defaults to SQLite.

git clone https://github.com/bvdr/familywell.git
cd familywell

composer install
npm install

cp .env.example .env
php artisan key:generate
touch database/database.sqlite

php artisan migrate          # core tables
php artisan modules:migrate  # module tables

composer dev                 # serves the app + queue + logs + Vite together

Open http://localhost:8000, register an account (the first user creates a family), then enable a module from Settings → Modules.

composer dev runs the PHP server, the queue worker, the log tailer, and the Vite dev server concurrently. Run npm run build for a production asset build.

Self-hosting

The whole app is a single image with a docker compose stack (app + Reverb + Postgres + Redis):

cp .env.example .env
php artisan key:generate            # or generate an APP_KEY and paste it into .env
docker compose up -d
docker compose exec app php artisan migrate --force
docker compose exec app php artisan modules:migrate

A prebuilt image is published at ghcr.io/bvdr/familywell. See docs/self-hosting.md for the full guide, including storage and Reverb configuration.

Public demo account (optional)

A "Try the live demo" button appears on the login page once a demo family exists. Visitors are signed
in as its owner with one click (/demo), can change anything, and the family is wiped and re-seeded
at the top of every hour by the scheduler (demo:reset).

php artisan db:seed --class=DemoSeeder --force   # once: creates the demo family (flagged is_demo)
php artisan demo:reset                           # any time: wipe + re-seed it (what the scheduler runs)

The reset locates the family only by the families.is_demo flag and refuses to run unless exactly
one family carries it, so it can never touch a real family.

Configuration

Everything is configured through environment variables in .env. See docs/configuration.md for the complete reference. Highlights:

AI receipt scanning (optional)

When a Google Gemini API key is present, spends gain a Scan receipt action: snap a photo and the amount, currency, date, category, shop, and a note are read from it and pre-filled for you to review and save. It costs roughly $0.001 per scan and reads rotated, low-quality, multilingual receipts.

The feature is entirely gated on the key, without it there is no button and the endpoint returns 404. To enable it, get a free key at aistudio.google.com/apikey and set:

GEMINI_API_KEY=your-key-here

AI categorisation (optional)

With a TypeSafe key, shopping items added into the catch-all Other aisle are sorted into the shop's best-fit aisle (Dairy, Produce, Plumbing, ...) right after they're saved, expenses saved into "Other" get a category the same way, and Spending settings has a one-tap Sort "Other" with AI for the backlog, with a progress bar:

TYPESAFE_API_KEY=your-key-here

No secrets are ever committed; .env and every credential file are git-ignored.

Modules

FamilyWell's features live in modules/. Each module is a self-contained folder with its own routes, controllers, models, migrations, and (optionally) a frontend bundle, registered through a service provider and a module.json manifest. Every feature listed above is a module; modules/important_todos is a small example to start from.

To learn how the module system works and how to build your own, see docs/modules.md.

Project structure

app/            Core Laravel application (families, auth, sharing, modules)
modules/        Self-contained feature modules (shopping, tasks, calendar, spending, ...)
resources/js/   React + Inertia frontend (pages, components, layouts)
routes/         Core web routes
docs/           Documentation and design notes
.do/            DigitalOcean App Platform deploy config (non-secret)

Contributing

Contributions are welcome: bug fixes, new modules, translations, docs. Start with CONTRIBUTING.md for the workflow, conventions, and the terms your contribution is accepted under.

License

FamilyWell is licensed under the PolyForm Noncommercial License 1.0.0. It's source-available, not open source:

• Allowed: personal and family use, self-hosting for your own household, studying, modifying and sharing the code for noncommercial purposes. Noncommercial organisations (a charity, a school, a public research group) may use it too, as the license defines.
• Not allowed: any commercial use, including selling or reselling FamilyWell or a modified version, offering it as a paid or hosted service, or using it inside a business.

Any copy or modified version must keep the license and its Required Notice line. For commercial licensing, contact the maintainer through familywell.co.